diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index ef6e38a734..d047c8c712 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -1,31 +1,68 @@ ---- name: Rust +permissions: + actions: read + on: push: - branches: [main] + branches: [ main ] pull_request: - branches: [main] - -permissions: - contents: read + branches: [ main ] env: CARGO_TERM_COLOR: always - ACTIONS_LINTS_TOOLCHAIN: 1.53.0 + CARGO_PROJECT_FEATURES: "v2021_3" + # Minimum supported Rust version (MSRV) + ACTION_MSRV_TOOLCHAIN: 1.54.0 + # Pinned toolchain for linting + ACTION_LINTS_TOOLCHAIN: 1.56.0 jobs: + build: + runs-on: ubuntu-latest + container: quay.io/coreos-assembler/fcos-buildroot:testing-devel + steps: + - uses: actions/checkout@v2 + - name: Cache Dependencies + uses: Swatinem/rust-cache@ce325b60658c1b38465c06cc965b79baf32c1e72 + - name: Build + run: cargo build --verbose --features=${{ env['CARGO_PROJECT_FEATURES'] }} + - name: Run tests + run: cargo test --verbose --features=${{ env['CARGO_PROJECT_FEATURES'] }} + build-minimum-toolchain: + name: "Build, minimum supported toolchain (MSRV)" + runs-on: ubuntu-latest + container: quay.io/coreos-assembler/fcos-buildroot:testing-devel + steps: + - name: Checkout repository + uses: actions/checkout@v2 + - name: Remove system Rust toolchain + run: dnf remove -y rust cargo + - name: Install toolchain + uses: actions-rs/toolchain@v1 + with: + toolchain: ${{ env['ACTION_MSRV_TOOLCHAIN'] }} + default: true + - name: Cache Dependencies + uses: Swatinem/rust-cache@ce325b60658c1b38465c06cc965b79baf32c1e72 + - name: cargo build + run: cargo build --features=${{ env['CARGO_PROJECT_FEATURES'] }} linting: name: "Lints, pinned toolchain" runs-on: ubuntu-latest + container: quay.io/coreos-assembler/fcos-buildroot:testing-devel steps: - name: Checkout repository uses: actions/checkout@v2 + - name: Remove system Rust toolchain + run: dnf remove -y rust cargo - name: Install toolchain uses: actions-rs/toolchain@v1 with: - toolchain: ${{ env['ACTIONS_LINTS_TOOLCHAIN'] }} + toolchain: ${{ env['ACTION_LINTS_TOOLCHAIN'] }} default: true components: rustfmt, clippy - name: cargo fmt (check) - run: cargo fmt -- --check -l + run: cargo fmt -p ostree -- --check -l + - name: cargo clippy (warnings) + run: cargo clippy -p ostree --features=${{ env['CARGO_PROJECT_FEATURES'] }} -- -D warnings diff --git a/Cargo.toml b/Cargo.toml index b2aa3f4e5e..7c849bf5c5 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,94 @@ -# Today, this repository only uses Rust for tests. This -# toplevel Cargo.toml helps tools like rust-analyzer understand -# that this project contains Rust code. We don't otherwise currently -# use `cargo` for any part of the core build. +[package] +authors = ["Felix Krull"] +description = "Rust bindings for libostree" +documentation = "https://docs.rs/ostree" +edition = "2018" +keywords = ["ostree", "libostree"] +license = "MIT" +name = "ostree" +readme = "README.md" +repository = "https://github.com/ostreedev/ostree-rs" +version = "0.13.6" + +exclude = [ + "rust-bindings/conf/**", + "rust-bindings/gir-files/**", + "rust-bindings/sys/**", + ".gitlab-ci.yml", + "LICENSE.LGPL*", +] + +[package.metadata.docs.rs] +features = ["dox"] + +[lib] +name = "ostree" +path = "rust-bindings/src/lib.rs" + [workspace] -members = ["tests/inst"] +members = [".", "rust-bindings/sys"] + +[dependencies] +bitflags = "1.2.1" +cap-std = { version = "0.24", optional = true} +io-lifetimes = { version = "0.5", optional = true} +ffi = { package = "ostree-sys", path = "rust-bindings/sys", version = "0.9.1" } +gio = "0.14" +glib = "0.14.4" +hex = "0.4.2" +libc = "0.2" +once_cell = "1.4.0" +radix64 = "0.6.2" +thiserror = "1.0.20" + +[dev-dependencies] +maplit = "1.0.2" +openat = "0.1.19" +tempfile = "3" +cap-tempfile = "0.24" + +[features] +cap-std-apis = ["cap-std", "io-lifetimes", "v2017_10"] +dox = ["ffi/dox"] +v2014_9 = ["ffi/v2014_9"] +v2015_7 = ["v2014_9", "ffi/v2015_7"] +v2016_3 = ["v2015_7", "ffi/v2016_3"] +v2016_4 = ["v2016_3", "ffi/v2016_4"] +v2016_5 = ["v2016_4", "ffi/v2016_5"] +v2016_6 = ["v2016_5", "ffi/v2016_6"] +v2016_7 = ["v2016_6", "ffi/v2016_7"] +v2016_8 = ["v2016_7", "ffi/v2016_8"] +v2016_14 = ["v2016_8", "ffi/v2016_14"] +v2017_1 = ["v2016_14", "ffi/v2017_1"] +v2017_2 = ["v2017_1", "ffi/v2017_2"] +v2017_3 = ["v2017_2", "ffi/v2017_3"] +v2017_4 = ["v2017_3", "ffi/v2017_4"] +v2017_6 = ["v2017_4", "ffi/v2017_6"] +v2017_7 = ["v2017_6", "ffi/v2017_7"] +v2017_8 = ["v2017_7", "ffi/v2017_8"] +v2017_9 = ["v2017_8", "ffi/v2017_9"] +v2017_10 = ["v2017_9", "ffi/v2017_10"] +v2017_11 = ["v2017_10", "ffi/v2017_11"] +v2017_12 = ["v2017_11", "ffi/v2017_12"] +v2017_13 = ["v2017_12", "ffi/v2017_13"] +v2017_15 = ["v2017_13", "ffi/v2017_15"] +v2018_2 = ["v2017_15", "ffi/v2018_2"] +v2018_3 = ["v2018_2", "ffi/v2018_3"] +v2018_5 = ["v2018_3", "ffi/v2018_5"] +v2018_6 = ["v2018_5", "ffi/v2018_6"] +v2018_7 = ["v2018_6", "ffi/v2018_7"] +v2018_9 = ["v2018_7", "ffi/v2018_9"] +v2019_2 = ["v2018_9", "ffi/v2019_2"] +v2019_3 = ["v2019_2", "ffi/v2019_3"] +v2019_4 = ["v2019_3", "ffi/v2019_4"] +v2019_6 = ["v2019_4", "ffi/v2019_6"] +v2020_1 = ["v2019_6", "ffi/v2020_1"] +v2020_2 = ["v2020_1", "ffi/v2020_2"] +v2020_4 = ["v2020_2", "ffi/v2020_4"] +v2020_7 = ["v2020_4", "ffi/v2020_7"] +v2020_8 = ["v2020_7", "ffi/v2020_8"] +v2021_1 = ["v2020_8", "ffi/v2021_1"] +v2021_2 = ["v2021_1", "ffi/v2021_2"] +v2021_3 = ["v2021_2", "ffi/v2021_3"] +v2021_4 = ["v2021_3", "ffi/v2021_4"] +v2021_5 = ["v2021_4", "ffi/v2021_5"] diff --git a/cfg.mk b/cfg.mk index 1f5108b770..471ccbc918 100644 --- a/cfg.mk +++ b/cfg.mk @@ -1,4 +1,4 @@ -export VC_LIST_EXCEPT_DEFAULT=^(docs/.*|git.mk|lib/.*|m4/.*|md5/.*|build-aux/.*|src/gettext\.h|.*ChangeLog|buildutil/.*)$$ +export VC_LIST_EXCEPT_DEFAULT=^(rust-bindings/.*|docs/.*|git.mk|lib/.*|m4/.*|md5/.*|build-aux/.*|src/gettext\.h|.*ChangeLog|buildutil/.*)$$ local-checks-to-skip = \ sc_const_long_option \ diff --git a/rust-bindings/.ci/generate-test-jobs.sh b/rust-bindings/.ci/generate-test-jobs.sh new file mode 100755 index 0000000000..2e83155272 --- /dev/null +++ b/rust-bindings/.ci/generate-test-jobs.sh @@ -0,0 +1,28 @@ +#!/bin/sh +set -eu + +get_features() { + cargo read-manifest \ + | jq -jr '.features + | keys + | map(select(. != "dox")) + | map(. + " ") + | .[]' +} + +cat <<EOF +include: /.ci/gitlab-ci-base.yml +EOF + +features=$(get_features) + +for feature in $features; do + +cat <<EOF +test_feature_${feature}: + extends: .fedora-ostree-devel + script: + - cargo test --verbose --workspace --features ${feature} +EOF + +done diff --git a/rust-bindings/.ci/gitlab-ci-base.yml b/rust-bindings/.ci/gitlab-ci-base.yml new file mode 100644 index 0000000000..afc6bbe35e --- /dev/null +++ b/rust-bindings/.ci/gitlab-ci-base.yml @@ -0,0 +1,31 @@ +.sccache: + variables: + SCCACHE_URL: https://github.com/mozilla/sccache/releases/download/0.2.13/sccache-0.2.13-x86_64-unknown-linux-musl.tar.gz + CARGO_TARGET_DIR: ${CI_PROJECT_DIR}/target + CARGO_HOME: ${CI_PROJECT_DIR}/cargo + SCCACHE_DIR: ${CI_PROJECT_DIR}/sccache + RUSTC_WRAPPER: sccache + cache: + paths: + - cargo/ + - sccache/ + +# config with sccache based on Fedora Rawhide, i.e. very recent libostree +.fedora-ostree-devel: + image: registry.fedoraproject.org/fedora:rawhide + extends: .sccache + before_script: + - dnf install -y cargo rust ostree-devel + - curl -L "${SCCACHE_URL}" | tar -C /usr/bin/ -xz --wildcards --strip-components=1 '*/sccache' + # ??? This seems to not work correctly on Fedora Rawhide right now? + - ln -s /usr/bin/x86_64-redhat-linux-gnu-pkg-config /usr/bin/x86_64-redhat-linux-pkg-config + +# config with sccache based on Rust image, i.e. older libostree but shorter setup and rustup access +.rust-ostree-devel: + image: rust + extends: .sccache + before_script: + - apt-get update + - apt-get install -y libostree-dev + - curl -L "${SCCACHE_URL}" | tar -C /usr/bin/ -xz --wildcards --strip-components=1 '*/sccache' + diff --git a/rust-bindings/.gitignore b/rust-bindings/.gitignore new file mode 100644 index 0000000000..155a4e1114 --- /dev/null +++ b/rust-bindings/.gitignore @@ -0,0 +1,7 @@ +.idea +target +cargo +sccache +**/*.rs.bk +Cargo.lock +.vagrant diff --git a/rust-bindings/LICENSE b/rust-bindings/LICENSE new file mode 100644 index 0000000000..bd32f32155 --- /dev/null +++ b/rust-bindings/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2018, 2019, 2020 Felix Krull + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/rust-bindings/LICENSE.LGPL2 b/rust-bindings/LICENSE.LGPL2 new file mode 100644 index 0000000000..5bc8fb2c8f --- /dev/null +++ b/rust-bindings/LICENSE.LGPL2 @@ -0,0 +1,481 @@ + GNU LIBRARY GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1991 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +[This is the first released version of the library GPL. It is + numbered 2 because it goes with version 2 of the ordinary GPL.] + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +Licenses are intended to guarantee your freedom to share and change +free software--to make sure the software is free for all its users. + + This license, the Library General Public License, applies to some +specially designated Free Software Foundation software, and to any +other libraries whose authors decide to use it. You can use it for +your libraries, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if +you distribute copies of the library, or if you modify it. + + For example, if you distribute copies of the library, whether gratis +or for a fee, you must give the recipients all the rights that we gave +you. You must make sure that they, too, receive or can get the source +code. If you link a program with the library, you must provide +complete object files to the recipients so that they can relink them +with the library, after making changes to the library and recompiling +it. And you must show them these terms so they know their rights. + + Our method of protecting your rights has two steps: (1) copyright +the library, and (2) offer you this license which gives you legal +permission to copy, distribute and/or modify the library. + + Also, for each distributor's protection, we want to make certain +that everyone understands that there is no warranty for this free +library. If the library is modified by someone else and passed on, we +want its recipients to know that what they have is not the original +version, so that any problems introduced by others will not reflect on +the original authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that companies distributing free +software will individually obtain patent licenses, thus in effect +transforming the program into proprietary software. To prevent this, +we have made it clear that any patent must be licensed for everyone's +free use or not licensed at all. + + Most GNU software, including some libraries, is covered by the ordinary +GNU General Public License, which was designed for utility programs. This +license, the GNU Library General Public License, applies to certain +designated libraries. This license is quite different from the ordinary +one; be sure to read it in full, and don't assume that anything in it is +the same as in the ordinary license. + + The reason we have a separate public license for some libraries is that +they blur the distinction we usually make between modifying or adding to a +program and simply using it. Linking a program with a library, without +changing the library, is in some sense simply using the library, and is +analogous to running a utility program or application program. However, in +a textual and legal sense, the linked executable is a combined work, a +derivative of the original library, and the ordinary General Public License +treats it as such. + + Because of this blurred distinction, using the ordinary General +Public License for libraries did not effectively promote software +sharing, because most developers did not use the libraries. We +concluded that weaker conditions might promote sharing better. + + However, unrestricted linking of non-free programs would deprive the +users of those programs of all benefit from the free status of the +libraries themselves. This Library General Public License is intended to +permit developers of non-free programs to use free libraries, while +preserving your freedom as a user of such programs to change the free +libraries that are incorporated in them. (We have not seen how to achieve +this as regards changes in header files, but we have achieved it as regards +changes in the actual functions of the Library.) The hope is that this +will lead to faster development of free libraries. + + The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +"work based on the library" and a "work that uses the library". The +former contains code derived from the library, while the latter only +works together with the library. + + Note that it is possible for a library to be covered by the ordinary +General Public License rather than by this special one. + + GNU LIBRARY GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License Agreement applies to any software library which +contains a notice placed by the copyright holder or other authorized +party saying it may be distributed under the terms of this Library +General Public License (also called "this License"). Each licensee is +addressed as "you". + + A "library" means a collection of software functions and/or data +prepared so as to be conveniently linked with application programs +(which use some of those functions and data) to form executables. + + The "Library", below, refers to any such software library or work +which has been distributed under these terms. A "work based on the +Library" means either the Library or any derivative work under +copyright law: that is to say, a work containing the Library or a +portion of it, either verbatim or with modifications and/or translated +straightforwardly into another language. (Hereinafter, translation is +included without limitation in the term "modification".) + + "Source code" for a work means the preferred form of the work for +making modifications to it. For a library, complete source code means +all the source code for all modules it contains, plus any associated +interface definition files, plus the scripts used to control compilation +and installation of the library. + + Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running a program using the Library is not restricted, and output from +such a program is covered only if its contents constitute a work based +on the Library (independent of the use of the Library in a tool for +writing it). Whether that is true depends on what the Library does +and what the program that uses the Library does. + + 1. You may copy and distribute verbatim copies of the Library's +complete source code as you receive it, in any medium, provided that +you conspicuously and appropriately publish on each copy an +appropriate copyright notice and disclaimer of warranty; keep intact +all the notices that refer to this License and to the absence of any +warranty; and distribute a copy of this License along with the +Library. + + You may charge a fee for the physical act of transferring a copy, +and you may at your option offer warranty protection in exchange for a +fee. + + 2. You may modify your copy or copies of the Library or any portion +of it, thus forming a work based on the Library, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) The modified work must itself be a software library. + + b) You must cause the files modified to carry prominent notices + stating that you changed the files and the date of any change. + + c) You must cause the whole of the work to be licensed at no + charge to all third parties under the terms of this License. + + d) If a facility in the modified Library refers to a function or a + table of data to be supplied by an application program that uses + the facility, other than as an argument passed when the facility + is invoked, then you must make a good faith effort to ensure that, + in the event an application does not supply such function or + table, the facility still operates, and performs whatever part of + its purpose remains meaningful. + + (For example, a function in a library to compute square roots has + a purpose that is entirely well-defined independent of the + application. Therefore, Subsection 2d requires that any + application-supplied function or table used by this function must + be optional: if the application does not supply it, the square + root function must still compute square roots.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Library, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Library, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote +it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Library. + +In addition, mere aggregation of another work not based on the Library +with the Library (or with a work based on the Library) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may opt to apply the terms of the ordinary GNU General Public +License instead of this License to a given copy of the Library. To do +this, you must alter all the notices that refer to this License, so +that they refer to the ordinary GNU General Public License, version 2, +instead of to this License. (If a newer version than version 2 of the +ordinary GNU General Public License has appeared, then you can specify +that version instead if you wish.) Do not make any other change in +these notices. + + Once this change is made in a given copy, it is irreversible for +that copy, so the ordinary GNU General Public License applies to all +subsequent copies and derivative works made from that copy. + + This option is useful when you wish to copy part of the code of +the Library into a program that is not a library. + + 4. You may copy and distribute the Library (or a portion or +derivative of it, under Section 2) in object code or executable form +under the terms of Sections 1 and 2 above provided that you accompany +it with the complete corresponding machine-readable source code, which +must be distributed under the terms of Sections 1 and 2 above on a +medium customarily used for software interchange. + + If distribution of object code is made by offering access to copy +from a designated place, then offering equivalent access to copy the +source code from the same place satisfies the requirement to +distribute the source code, even though third parties are not +compelled to copy the source along with the object code. + + 5. A program that contains no derivative of any portion of the +Library, but is designed to work with the Library by being compiled or +linked with it, is called a "work that uses the Library". Such a +work, in isolation, is not a derivative work of the Library, and +therefore falls outside the scope of this License. + + However, linking a "work that uses the Library" with the Library +creates an executable that is a derivative of the Library (because it +contains portions of the Library), rather than a "work that uses the +library". The executable is therefore covered by this License. +Section 6 states terms for distribution of such executables. + + When a "work that uses the Library" uses material from a header file +that is part of the Library, the object code for the work may be a +derivative work of the Library even though the source code is not. +Whether this is true is especially significant if the work can be +linked without the Library, or if the work is itself a library. The +threshold for this to be true is not precisely defined by law. + + If such an object file uses only numerical parameters, data +structure layouts and accessors, and small macros and small inline +functions (ten lines or less in length), then the use of the object +file is unrestricted, regardless of whether it is legally a derivative +work. (Executables containing this object code plus portions of the +Library will still fall under Section 6.) + + Otherwise, if the work is a derivative of the Library, you may +distribute the object code for the work under the terms of Section 6. +Any executables containing that work also fall under Section 6, +whether or not they are linked directly with the Library itself. + + 6. As an exception to the Sections above, you may also compile or +link a "work that uses the Library" with the Library to produce a +work containing portions of the Library, and distribute that work +under terms of your choice, provided that the terms permit +modification of the work for the customer's own use and reverse +engineering for debugging such modifications. + + You must give prominent notice with each copy of the work that the +Library is used in it and that the Library and its use are covered by +this License. You must supply a copy of this License. If the work +during execution displays copyright notices, you must include the +copyright notice for the Library among them, as well as a reference +directing the user to the copy of this License. Also, you must do one +of these things: + + a) Accompany the work with the complete corresponding + machine-readable source code for the Library including whatever + changes were used in the work (which must be distributed under + Sections 1 and 2 above); and, if the work is an executable linked + with the Library, with the complete machine-readable "work that + uses the Library", as object code and/or source code, so that the + user can modify the Library and then relink to produce a modified + executable containing the modified Library. (It is understood + that the user who changes the contents of definitions files in the + Library will not necessarily be able to recompile the application + to use the modified definitions.) + + b) Accompany the work with a written offer, valid for at + least three years, to give the same user the materials + specified in Subsection 6a, above, for a charge no more + than the cost of performing this distribution. + + c) If distribution of the work is made by offering access to copy + from a designated place, offer equivalent access to copy the above + specified materials from the same place. + + d) Verify that the user has already received a copy of these + materials or that you have already sent this user a copy. + + For an executable, the required form of the "work that uses the +Library" must include any data and utility programs needed for +reproducing the executable from it. However, as a special exception, +the source code distributed need not include anything that is normally +distributed (in either source or binary form) with the major +components (compiler, kernel, and so on) of the operating system on +which the executable runs, unless that component itself accompanies +the executable. + + It may happen that this requirement contradicts the license +restrictions of other proprietary libraries that do not normally +accompany the operating system. Such a contradiction means you cannot +use both them and the Library together in an executable that you +distribute. + + 7. You may place library facilities that are a work based on the +Library side-by-side in a single library together with other library +facilities not covered by this License, and distribute such a combined +library, provided that the separate distribution of the work based on +the Library and of the other library facilities is otherwise +permitted, and provided that you do these two things: + + a) Accompany the combined library with a copy of the same work + based on the Library, uncombined with any other library + facilities. This must be distributed under the terms of the + Sections above. + + b) Give prominent notice with the combined library of the fact + that part of it is a work based on the Library, and explaining + where to find the accompanying uncombined form of the same work. + + 8. You may not copy, modify, sublicense, link with, or distribute +the Library except as expressly provided under this License. Any +attempt otherwise to copy, modify, sublicense, link with, or +distribute the Library is void, and will automatically terminate your +rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses +terminated so long as such parties remain in full compliance. + + 9. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Library or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Library (or any work based on the +Library), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Library or works based on it. + + 10. Each time you redistribute the Library (or any work based on the +Library), the recipient automatically receives a license from the +original licensor to copy, distribute, link with or modify the Library +subject to these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 11. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Library at all. For example, if a patent +license would not permit royalty-free redistribution of the Library by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Library. + +If any portion of this section is held invalid or unenforceable under any +particular circumstance, the balance of the section is intended to apply, +and the section as a whole is intended to apply in other circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 12. If the distribution and/or use of the Library is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Library under this License may add +an explicit geographical distribution limitation excluding those countries, +so that distribution is permitted only in or among countries not thus +excluded. In such case, this License incorporates the limitation as if +written in the body of this License. + + 13. The Free Software Foundation may publish revised and/or new +versions of the Library General Public License from time to time. +Such new versions will be similar in spirit to the present version, +but may differ in detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Library +specifies a version number of this License which applies to it and +"any later version", you have the option of following the terms and +conditions either of that version or of any later version published by +the Free Software Foundation. If the Library does not specify a +license version number, you may choose any version ever published by +the Free Software Foundation. + + 14. If you wish to incorporate parts of the Library into other free +programs whose distribution conditions are incompatible with these, +write to the author to ask for permission. For software which is +copyrighted by the Free Software Foundation, write to the Free +Software Foundation; we sometimes make exceptions for this. Our +decision will be guided by the two goals of preserving the free status +of all derivatives of our free software and of promoting the sharing +and reuse of software generally. + + NO WARRANTY + + 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO +WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY +KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE +LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY +AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU +FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING +RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A +FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF +SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Libraries + + If you develop a new library, and you want it to be of the greatest +possible use to the public, we recommend making it free software that +everyone can redistribute and change. You can do so by permitting +redistribution under these terms (or, alternatively, under the terms of the +ordinary General Public License). + + To apply these terms, attach the following notices to the library. It is +safest to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + + <one line to give the library's name and a brief idea of what it does.> + Copyright (C) <year> <name of author> + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +Also add information on how to contact you by electronic and paper mail. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the library, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the + library `Frob' (a library for tweaking knobs) written by James Random Hacker. + + <signature of Ty Coon>, 1 April 1990 + Ty Coon, President of Vice + +That's all there is to it! diff --git a/rust-bindings/LICENSE.LGPL2.1 b/rust-bindings/LICENSE.LGPL2.1 new file mode 100644 index 0000000000..4362b49151 --- /dev/null +++ b/rust-bindings/LICENSE.LGPL2.1 @@ -0,0 +1,502 @@ + GNU LESSER GENERAL PUBLIC LICENSE + Version 2.1, February 1999 + + Copyright (C) 1991, 1999 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +[This is the first released version of the Lesser GPL. It also counts + as the successor of the GNU Library Public License, version 2, hence + the version number 2.1.] + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +Licenses are intended to guarantee your freedom to share and change +free software--to make sure the software is free for all its users. + + This license, the Lesser General Public License, applies to some +specially designated software packages--typically libraries--of the +Free Software Foundation and other authors who decide to use it. You +can use it too, but we suggest you first think carefully about whether +this license or the ordinary General Public License is the better +strategy to use in any particular case, based on the explanations below. + + When we speak of free software, we are referring to freedom of use, +not price. Our General Public Licenses are designed to make sure that +you have the freedom to distribute copies of free software (and charge +for this service if you wish); that you receive source code or can get +it if you want it; that you can change the software and use pieces of +it in new free programs; and that you are informed that you can do +these things. + + To protect your rights, we need to make restrictions that forbid +distributors to deny you these rights or to ask you to surrender these +rights. These restrictions translate to certain responsibilities for +you if you distribute copies of the library or if you modify it. + + For example, if you distribute copies of the library, whether gratis +or for a fee, you must give the recipients all the rights that we gave +you. You must make sure that they, too, receive or can get the source +code. If you link other code with the library, you must provide +complete object files to the recipients, so that they can relink them +with the library after making changes to the library and recompiling +it. And you must show them these terms so they know their rights. + + We protect your rights with a two-step method: (1) we copyright the +library, and (2) we offer you this license, which gives you legal +permission to copy, distribute and/or modify the library. + + To protect each distributor, we want to make it very clear that +there is no warranty for the free library. Also, if the library is +modified by someone else and passed on, the recipients should know +that what they have is not the original version, so that the original +author's reputation will not be affected by problems that might be +introduced by others. + + Finally, software patents pose a constant threat to the existence of +any free program. We wish to make sure that a company cannot +effectively restrict the users of a free program by obtaining a +restrictive license from a patent holder. Therefore, we insist that +any patent license obtained for a version of the library must be +consistent with the full freedom of use specified in this license. + + Most GNU software, including some libraries, is covered by the +ordinary GNU General Public License. This license, the GNU Lesser +General Public License, applies to certain designated libraries, and +is quite different from the ordinary General Public License. We use +this license for certain libraries in order to permit linking those +libraries into non-free programs. + + When a program is linked with a library, whether statically or using +a shared library, the combination of the two is legally speaking a +combined work, a derivative of the original library. The ordinary +General Public License therefore permits such linking only if the +entire combination fits its criteria of freedom. The Lesser General +Public License permits more lax criteria for linking other code with +the library. + + We call this license the "Lesser" General Public License because it +does Less to protect the user's freedom than the ordinary General +Public License. It also provides other free software developers Less +of an advantage over competing non-free programs. These disadvantages +are the reason we use the ordinary General Public License for many +libraries. However, the Lesser license provides advantages in certain +special circumstances. + + For example, on rare occasions, there may be a special need to +encourage the widest possible use of a certain library, so that it becomes +a de-facto standard. To achieve this, non-free programs must be +allowed to use the library. A more frequent case is that a free +library does the same job as widely used non-free libraries. In this +case, there is little to gain by limiting the free library to free +software only, so we use the Lesser General Public License. + + In other cases, permission to use a particular library in non-free +programs enables a greater number of people to use a large body of +free software. For example, permission to use the GNU C Library in +non-free programs enables many more people to use the whole GNU +operating system, as well as its variant, the GNU/Linux operating +system. + + Although the Lesser General Public License is Less protective of the +users' freedom, it does ensure that the user of a program that is +linked with the Library has the freedom and the wherewithal to run +that program using a modified version of the Library. + + The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +"work based on the library" and a "work that uses the library". The +former contains code derived from the library, whereas the latter must +be combined with the library in order to run. + + GNU LESSER GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License Agreement applies to any software library or other +program which contains a notice placed by the copyright holder or +other authorized party saying it may be distributed under the terms of +this Lesser General Public License (also called "this License"). +Each licensee is addressed as "you". + + A "library" means a collection of software functions and/or data +prepared so as to be conveniently linked with application programs +(which use some of those functions and data) to form executables. + + The "Library", below, refers to any such software library or work +which has been distributed under these terms. A "work based on the +Library" means either the Library or any derivative work under +copyright law: that is to say, a work containing the Library or a +portion of it, either verbatim or with modifications and/or translated +straightforwardly into another language. (Hereinafter, translation is +included without limitation in the term "modification".) + + "Source code" for a work means the preferred form of the work for +making modifications to it. For a library, complete source code means +all the source code for all modules it contains, plus any associated +interface definition files, plus the scripts used to control compilation +and installation of the library. + + Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running a program using the Library is not restricted, and output from +such a program is covered only if its contents constitute a work based +on the Library (independent of the use of the Library in a tool for +writing it). Whether that is true depends on what the Library does +and what the program that uses the Library does. + + 1. You may copy and distribute verbatim copies of the Library's +complete source code as you receive it, in any medium, provided that +you conspicuously and appropriately publish on each copy an +appropriate copyright notice and disclaimer of warranty; keep intact +all the notices that refer to this License and to the absence of any +warranty; and distribute a copy of this License along with the +Library. + + You may charge a fee for the physical act of transferring a copy, +and you may at your option offer warranty protection in exchange for a +fee. + + 2. You may modify your copy or copies of the Library or any portion +of it, thus forming a work based on the Library, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) The modified work must itself be a software library. + + b) You must cause the files modified to carry prominent notices + stating that you changed the files and the date of any change. + + c) You must cause the whole of the work to be licensed at no + charge to all third parties under the terms of this License. + + d) If a facility in the modified Library refers to a function or a + table of data to be supplied by an application program that uses + the facility, other than as an argument passed when the facility + is invoked, then you must make a good faith effort to ensure that, + in the event an application does not supply such function or + table, the facility still operates, and performs whatever part of + its purpose remains meaningful. + + (For example, a function in a library to compute square roots has + a purpose that is entirely well-defined independent of the + application. Therefore, Subsection 2d requires that any + application-supplied function or table used by this function must + be optional: if the application does not supply it, the square + root function must still compute square roots.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Library, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Library, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote +it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Library. + +In addition, mere aggregation of another work not based on the Library +with the Library (or with a work based on the Library) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may opt to apply the terms of the ordinary GNU General Public +License instead of this License to a given copy of the Library. To do +this, you must alter all the notices that refer to this License, so +that they refer to the ordinary GNU General Public License, version 2, +instead of to this License. (If a newer version than version 2 of the +ordinary GNU General Public License has appeared, then you can specify +that version instead if you wish.) Do not make any other change in +these notices. + + Once this change is made in a given copy, it is irreversible for +that copy, so the ordinary GNU General Public License applies to all +subsequent copies and derivative works made from that copy. + + This option is useful when you wish to copy part of the code of +the Library into a program that is not a library. + + 4. You may copy and distribute the Library (or a portion or +derivative of it, under Section 2) in object code or executable form +under the terms of Sections 1 and 2 above provided that you accompany +it with the complete corresponding machine-readable source code, which +must be distributed under the terms of Sections 1 and 2 above on a +medium customarily used for software interchange. + + If distribution of object code is made by offering access to copy +from a designated place, then offering equivalent access to copy the +source code from the same place satisfies the requirement to +distribute the source code, even though third parties are not +compelled to copy the source along with the object code. + + 5. A program that contains no derivative of any portion of the +Library, but is designed to work with the Library by being compiled or +linked with it, is called a "work that uses the Library". Such a +work, in isolation, is not a derivative work of the Library, and +therefore falls outside the scope of this License. + + However, linking a "work that uses the Library" with the Library +creates an executable that is a derivative of the Library (because it +contains portions of the Library), rather than a "work that uses the +library". The executable is therefore covered by this License. +Section 6 states terms for distribution of such executables. + + When a "work that uses the Library" uses material from a header file +that is part of the Library, the object code for the work may be a +derivative work of the Library even though the source code is not. +Whether this is true is especially significant if the work can be +linked without the Library, or if the work is itself a library. The +threshold for this to be true is not precisely defined by law. + + If such an object file uses only numerical parameters, data +structure layouts and accessors, and small macros and small inline +functions (ten lines or less in length), then the use of the object +file is unrestricted, regardless of whether it is legally a derivative +work. (Executables containing this object code plus portions of the +Library will still fall under Section 6.) + + Otherwise, if the work is a derivative of the Library, you may +distribute the object code for the work under the terms of Section 6. +Any executables containing that work also fall under Section 6, +whether or not they are linked directly with the Library itself. + + 6. As an exception to the Sections above, you may also combine or +link a "work that uses the Library" with the Library to produce a +work containing portions of the Library, and distribute that work +under terms of your choice, provided that the terms permit +modification of the work for the customer's own use and reverse +engineering for debugging such modifications. + + You must give prominent notice with each copy of the work that the +Library is used in it and that the Library and its use are covered by +this License. You must supply a copy of this License. If the work +during execution displays copyright notices, you must include the +copyright notice for the Library among them, as well as a reference +directing the user to the copy of this License. Also, you must do one +of these things: + + a) Accompany the work with the complete corresponding + machine-readable source code for the Library including whatever + changes were used in the work (which must be distributed under + Sections 1 and 2 above); and, if the work is an executable linked + with the Library, with the complete machine-readable "work that + uses the Library", as object code and/or source code, so that the + user can modify the Library and then relink to produce a modified + executable containing the modified Library. (It is understood + that the user who changes the contents of definitions files in the + Library will not necessarily be able to recompile the application + to use the modified definitions.) + + b) Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (1) uses at run time a + copy of the library already present on the user's computer system, + rather than copying library functions into the executable, and (2) + will operate properly with a modified version of the library, if + the user installs one, as long as the modified version is + interface-compatible with the version that the work was made with. + + c) Accompany the work with a written offer, valid for at + least three years, to give the same user the materials + specified in Subsection 6a, above, for a charge no more + than the cost of performing this distribution. + + d) If distribution of the work is made by offering access to copy + from a designated place, offer equivalent access to copy the above + specified materials from the same place. + + e) Verify that the user has already received a copy of these + materials or that you have already sent this user a copy. + + For an executable, the required form of the "work that uses the +Library" must include any data and utility programs needed for +reproducing the executable from it. However, as a special exception, +the materials to be distributed need not include anything that is +normally distributed (in either source or binary form) with the major +components (compiler, kernel, and so on) of the operating system on +which the executable runs, unless that component itself accompanies +the executable. + + It may happen that this requirement contradicts the license +restrictions of other proprietary libraries that do not normally +accompany the operating system. Such a contradiction means you cannot +use both them and the Library together in an executable that you +distribute. + + 7. You may place library facilities that are a work based on the +Library side-by-side in a single library together with other library +facilities not covered by this License, and distribute such a combined +library, provided that the separate distribution of the work based on +the Library and of the other library facilities is otherwise +permitted, and provided that you do these two things: + + a) Accompany the combined library with a copy of the same work + based on the Library, uncombined with any other library + facilities. This must be distributed under the terms of the + Sections above. + + b) Give prominent notice with the combined library of the fact + that part of it is a work based on the Library, and explaining + where to find the accompanying uncombined form of the same work. + + 8. You may not copy, modify, sublicense, link with, or distribute +the Library except as expressly provided under this License. Any +attempt otherwise to copy, modify, sublicense, link with, or +distribute the Library is void, and will automatically terminate your +rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses +terminated so long as such parties remain in full compliance. + + 9. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Library or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Library (or any work based on the +Library), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Library or works based on it. + + 10. Each time you redistribute the Library (or any work based on the +Library), the recipient automatically receives a license from the +original licensor to copy, distribute, link with or modify the Library +subject to these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties with +this License. + + 11. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Library at all. For example, if a patent +license would not permit royalty-free redistribution of the Library by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Library. + +If any portion of this section is held invalid or unenforceable under any +particular circumstance, the balance of the section is intended to apply, +and the section as a whole is intended to apply in other circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 12. If the distribution and/or use of the Library is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Library under this License may add +an explicit geographical distribution limitation excluding those countries, +so that distribution is permitted only in or among countries not thus +excluded. In such case, this License incorporates the limitation as if +written in the body of this License. + + 13. The Free Software Foundation may publish revised and/or new +versions of the Lesser General Public License from time to time. +Such new versions will be similar in spirit to the present version, +but may differ in detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Library +specifies a version number of this License which applies to it and +"any later version", you have the option of following the terms and +conditions either of that version or of any later version published by +the Free Software Foundation. If the Library does not specify a +license version number, you may choose any version ever published by +the Free Software Foundation. + + 14. If you wish to incorporate parts of the Library into other free +programs whose distribution conditions are incompatible with these, +write to the author to ask for permission. For software which is +copyrighted by the Free Software Foundation, write to the Free +Software Foundation; we sometimes make exceptions for this. Our +decision will be guided by the two goals of preserving the free status +of all derivatives of our free software and of promoting the sharing +and reuse of software generally. + + NO WARRANTY + + 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO +WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY +KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE +LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY +AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU +FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING +RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A +FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF +SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Libraries + + If you develop a new library, and you want it to be of the greatest +possible use to the public, we recommend making it free software that +everyone can redistribute and change. You can do so by permitting +redistribution under these terms (or, alternatively, under the terms of the +ordinary General Public License). + + To apply these terms, attach the following notices to the library. It is +safest to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + + <one line to give the library's name and a brief idea of what it does.> + Copyright (C) <year> <name of author> + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +Also add information on how to contact you by electronic and paper mail. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the library, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the + library `Frob' (a library for tweaking knobs) written by James Random Hacker. + + <signature of Ty Coon>, 1 April 1990 + Ty Coon, President of Vice + +That's all there is to it! diff --git a/rust-bindings/Makefile b/rust-bindings/Makefile new file mode 100644 index 0000000000..d579cb45e8 --- /dev/null +++ b/rust-bindings/Makefile @@ -0,0 +1,65 @@ +GIR_REPO := https://github.com/gtk-rs/gir.git +GIR_VERSION := e8f82cf63f2b2fba7af9440248510c4b7e5ab787 +OSTREE_REPO := ../ostree +OSTREE_VERSION := patch-v2022.2 +RUSTDOC_STRIPPER_VERSION := 0.1.17 + +all: gir + +.PHONY: gir gir-report update-gir-files remove-gir-files merge-lgpl-docs ci-build-stages + + +# -- gir generation -- +target/tools/bin/gir: + cargo install --root target/tools --git $(GIR_REPO) --rev $(GIR_VERSION) -- gir + +gir: target/tools/bin/gir + target/tools/bin/gir -c conf/ostree-sys.toml + target/tools/bin/gir -c conf/ostree.toml + +gir-report: target/tools/bin/gir + target/tools/bin/gir -c conf/ostree.toml -m not_bound + + +# -- LGPL docs generation -- +target/tools/bin/rustdoc-stripper: + cargo install --root target/tools --version $(RUSTDOC_STRIPPER_VERSION) -- rustdoc-stripper + +merge-lgpl-docs: target/tools/bin/gir target/tools/bin/rustdoc-stripper + target/tools/bin/gir -c conf/ostree.toml -m doc + target/tools/bin/rustdoc-stripper -g -o target/vendor.md + + +# -- gir file management -- +update-gir-files: \ + remove-gir-files \ + gir-files \ + gir-files/GLib-2.0.gir \ + gir-files/Gio-2.0.gir \ + gir-files/GObject-2.0.gir \ + gir-files/OSTree-1.0.gir + +remove-gir-files: + rm -f gir-files/*.gir + +gir-files: + mkdir -p gir-files + +%.gir: + curl -o $@ -L https://github.com/gtk-rs/gir-files/raw/master/${@F} + +gir-files/OSTree-1.0.gir: + podman build \ + --pull \ + --build-arg OSTREE_REPO=$(OSTREE_REPO) \ + --build-arg OSTREE_VERSION=$(OSTREE_VERSION) \ + -t ostree-build \ + . + podman create \ + --name ostree-gir-container \ + ostree-build + podman cp \ + ostree-gir-container:/build/OSTree-1.0.gir \ + gir-files/OSTree-1.0.gir + podman rm \ + ostree-gir-container diff --git a/rust-bindings/README.md b/rust-bindings/README.md new file mode 100644 index 0000000000..f0165358ba --- /dev/null +++ b/rust-bindings/README.md @@ -0,0 +1,133 @@ +# ostree-rs +[![pipeline status](https://gitlab.com/fkrull/ostree-rs/badges/main/pipeline.svg)](https://gitlab.com/fkrull/ostree-rs/commits/main) +[![Crates.io](https://img.shields.io/crates/v/ostree.svg)](https://crates.io/crates/ostree) +[![main-docs](https://img.shields.io/badge/docs-main-brightgreen.svg)](https://fkrull.gitlab.io/ostree-rs/ostree) + +**Rust** bindings for [libostree](https://ostree.readthedocs.io). + +libostree is both a shared library and suite of command line tools that combines +a "git-like" model for committing and downloading bootable filesystem trees, +along with a layer for deploying them and managing the bootloader configuration. + +> **Note**: this crate was renamed from the `libostree` crate. + +## Status +Most bindings that can be auto-generated are being auto-generated by now. +Anything that is not yet supported by the crate probably requires handwritten +bindings. These will most likely be added on an as-needed basis. + +## Using + +### Requirements +The `ostree` crate requires libostree and the libostree development headers. + +On Debian and Ubuntu: +```ShellSession +$ sudo apt-get install libostree-1 libostree-dev +``` + +On Fedora and CentOS: +```ShellSession +$ sudo dnf install ostree-libs ostree-devel +``` + +### Installing +To use the crate, add it to your `Cargo.toml`: + +```toml +[dependencies] +ostree = "0.10" +``` + +To use features from later libostree versions, you need to specify the release +version as well: + +```toml +[dependencies.ostree] +version = "0.10" +features = ["v2021_1"] +``` + +## Developing +The `ostree` and `ostree-sys` crates can be built and tested using regular +Cargo commands. + +### Generated code +Most code is generated based on the gir files using the +[gir](https://github.com/gtk-rs/gir) tool. + +You can update `OSTree-1.0.gir` by directly copying it from a local ostree build. + +Or, these parts can be regenerated using +the included Makefile: + +```ShellSession +$ make gir +``` + +Run the following command to update the bundled gir files: + +```ShellSession +$ make update-gir-files +``` + +### Documentation +The libostree API documentation is not included in the code by default because +of its LGPL license. This means normal `cargo doc` runs don't include API docs +for the generated code. Run the `merge-lgpl-docs` Makefile target to include +the API docs in the source so they can be consumed by `cargo doc`: + +```ShellSession +$ make merge-lgpl-docs +``` + +Keep in mind that if you build the crate with the API docs included, it's +effectively LGPL-licensed and you need to comply with the LGPL requirements +(specifically, allowing users of your end product to swap out the LGPL'd +parts). + +CI includes the LGPL docs in the documentation build. + +### Updating glib-rs +* update `GIR_VERSION` in `Makefile` to the latest gir commit (matching the target glib-rs version) +* `make gir` to regenerate the generated code +* inspect differences in generated code +* update glib-rs dependencies in `Cargo.toml` and `sys/Cargo.toml` + +### Updating ostree +* update `OSTREE_VERSION` in `Makefile` +* `make update-gir-files` to update all gir files +* inspect differences in `OSTree-1.0.gir` +* `make gir` to regenerate the generated code +* add any new feature levels to `Cargo.toml` +* update the example feature level in `README.md` in case of a new feature level + +### Releases +Releases can be done using the publish_* jobs in the pipeline. There's no +versioning helper so version bumps need to be done manually. + +The version needs to be changed in the following places (if applicable): +* in `sys/Cargo.toml` for the -sys crate version +* in the `ostree-sys =` dependency in `Cargo.toml` +* in `Cargo.toml` for the main crate version +* in `README.md` in the *Installing* section in case of major version bumps + +Then tag the commit as `ostree/x.y.z` and/or `ostree-sys/x.y.z`. This will run +the crates.io deployment jobs. Main and -sys crate don't have to be released in +lockstep. + +## License +The `ostree` crate is licensed under the MIT license. See the LICENSE file for +details. + +libostree itself is licensed under the LGPL2+. See its +[licensing information](https://ostree.readthedocs.io#licensing) for more +information. + +The libostree GIR file (`gir-files/OSTree-1.0.gir`) is derived from the +libostree source code and is also licensed under the LGPL2+. A copy of the +LGPL version 2 is included in the LICENSE.LGPL2 file. + +The remaining GIR files (`gir-files/*.gir`) are from the glib project and +are licensed under the LGPL2.1+. A copy of the LGPL version 2.1 is included +in the LICENSE.LGPL2.1 file. diff --git a/rust-bindings/conf/ostree-sys.toml b/rust-bindings/conf/ostree-sys.toml new file mode 100644 index 0000000000..f5f664db0c --- /dev/null +++ b/rust-bindings/conf/ostree-sys.toml @@ -0,0 +1,39 @@ +[options] +work_mode = "sys" +library = "OSTree" +version = "1.0" +target_path = "../sys" +single_version_file = true +external_libraries = [ + "GLib", + "GObject", + "Gio", +] +ignore = [ + # private API (not in installed headers) + "OSTree.BootloaderInterface", + "OSTree.ChecksumInputStream", + "OSTree.ChecksumInputStreamClass", + "OSTree.CmdPrivateVTable", + "OSTree.LibarchiveInputStream", + "OSTree.LibarchiveInputStreamClass", + "OSTree.LzmaCompressorClass", + "OSTree.LzmaDecompressorClass", + "OSTree.RepoFileEnumeratorClass", + "OSTree.RollsumMatches", + "OSTree.SignDummy", + "OSTree.SignDummyClass", + "OSTree.SignEd25519", + "OSTree.SignEd25519Class", + + # version-dependent constants + "OSTree.RELEASE_VERSION", + "OSTree.VERSION", + "OSTree.VERSION_S", + "OSTree.YEAR_VERSION", + + # build-dependent constants + "OSTree.BUILT_FEATURES", +] + +girs_directories = [ "../gir-files" ] diff --git a/rust-bindings/conf/ostree.toml b/rust-bindings/conf/ostree.toml new file mode 100644 index 0000000000..64abc10ae5 --- /dev/null +++ b/rust-bindings/conf/ostree.toml @@ -0,0 +1,266 @@ +# Legend: +# - [IGNORE] we don't want to autogenerate this +# - [MANUAL] we have manual wrappers for this, but would prefer to autogenerate it +# - [FAIL] this is currently disabled because it generates broken code + +[options] +work_mode = "normal" +library = "OSTree" +version = "1.0" +target_path = ".." +doc_target_path = "../target/vendor.md" +deprecate_by_min_version = true +single_version_file = true +generate_display_trait = true + +girs_directories = [ "../gir-files" ] + +generate = [ + "OSTree.AsyncProgress", + "OSTree.BootconfigParser", + "OSTree.ChecksumFlags", + "OSTree.ContentWriter", + "OSTree.CommitSizesEntry", + "OSTree.Deployment", + "OSTree.DeploymentUnlockedState", + "OSTree.DiffFlags", + "OSTree.DiffItem", + "OSTree.GpgSignatureAttr", + "OSTree.GpgSignatureFormatFlags", + "OSTree.GpgVerifyResult", + "OSTree.MutableTree", + "OSTree.ObjectType", + "OSTree.Remote", + "OSTree.RepoCheckoutFilterResult", + "OSTree.RepoCheckoutMode", + "OSTree.RepoCheckoutOverwriteMode", + "OSTree.RepoCommitFilterResult", + "OSTree.RepoCommitFilter", + "OSTree.RepoCommitIterResult", + "OSTree.RepoCommitModifierFlags", + "OSTree.RepoCommitTraverseFlags", + "OSTree.RepoCommitModifier", + "OSTree.RepoCommitState", + "OSTree.RepoDevInoCache", + "OSTree.RepoFile", + "OSTree.RepoFinderAvahi", + "OSTree.RepoFinderConfig", + "OSTree.RepoFinderMount", + "OSTree.RepoFinderOverride", + "OSTree.RepoListObjectsFlags", + "OSTree.RepoListRefsExtFlags", + "OSTree.RepoMode", + "OSTree.RepoPruneFlags", + "OSTree.RepoPullFlags", + "OSTree.RepoRemoteChange", + "OSTree.RepoResolveRevExtFlags", + "OSTree.RepoVerifyFlags", + "OSTree.SePolicyRestoreconFlags", + "OSTree.StaticDeltaGenerateOpt", + "OSTree.SysrootSimpleWriteDeploymentFlags", + "OSTree.SysrootUpgrader", + "OSTree.SysrootUpgraderFlags", + "OSTree.SysrootUpgraderPullFlags", +] + +manual = [ + # types from glib/gio we need + "Gio.AsyncReadyCallback", + "Gio.AsyncResult", + "Gio.Cancellable", + "Gio.File", + "Gio.FileInfo", + "Gio.FileQueryInfoFlags", + "Gio.FilterInputStream", + "Gio.InputStream", + "Gio.OutputStream", + "Gio.VolumeMonitor", + "GLib.Bytes", + "GLib.Checksum", + "GLib.DestroyNotify", + "GLib.Error", + "GLib.KeyFile", + "GLib.MainContext", + "GLib.Quark", + "GLib.String", + "GLib.Variant", + "GLib.VariantType", + + # [MANUAL] types implemented by hand + "OSTree.KernelArgs", + "OSTree.RepoCheckoutAtOptions", + "OSTree.RepoCheckoutFilter", + "OSTree.RepoTransactionStats", + "OSTree.SysrootWriteDeploymentsOpts", + "OSTree.SysrootDeployTreeOpts", +] + +ignore = [ + # only used for the already-deprecated checkout_tree_at function + "OSTree.RepoCheckoutOptions", + # types for zero-terminated arrays we probably don't want + "OSTree.CollectionRefv", + "OSTree.RepoFinderResultv", + # not part of the public interface, as far as I can tell + "OSTree.Bootloader", + "OSTree.BootloaderGrub2", + "OSTree.BootloaderInterface", + "OSTree.BootloaderSyslinux", + "OSTree.BootloaderUboot", + "OSTree.BootloaderZipl", + "OSTree.ChecksumInputStream", + "OSTree.ChecksumInputStreamBuilder", + "OSTree.CmdPrivateVTable", + "OSTree.GpgVerifier", + "OSTree.LibarchiveInputStream", + "OSTree.LzmaCompressor", + "OSTree.LzmaDecompressor", + "OSTree.RollsumMatches", + # builders we don't want + "OSTree.RepoBuilder", + "OSTree.RepoFinderMountBuilder", + "OSTree.SePolicyBuilder", + "OSTree.SysrootBuilder", + "OSTree.SysrootUpgraderBuilder", +] + +[crate_name_overrides] +os_tree = "ostree" + +[[object]] +name = "OSTree.CollectionRef" +status = "generate" + [[object.function]] + # [IGNORE] helper functions for NULL-terminated arrays + pattern = "^(dupv|freev)$" + ignore = true + + [[object.function]] + # [IGNORE] clone() should already be this + name = "dup" + ignore = true + +[[object]] +name = "OSTree.Repo" +status = "generate" +concurrency = "send" + [[object.function]] + # [MANUAL] we special-case the checksum value + pattern = "^(write_content|write_content_async|write_metadata|write_metadata_async)$" + ignore = true + + [[object.function]] + # [FAIL] these fail because of issues with arrays of dubious lifetimes + pattern = "^(find_remotes_async|pull_from_remotes_async)$" + ignore = true + + [[object.function]] + # [IGNORE] this is deprecated and supposedly unsafe for GI + name = "checkout_tree_at" + ignore = true + + [[object.function]] + name = "checkout_at" + [[object.function.parameter]] + name = "options" + const = true + [[object.function.parameter]] + name = "destination_path" + string_type = "filename" + +[[object]] +name = "OSTree.RepoFinder" +status = "generate" + [[object.function]] + # [FAIL] these fail because of issues with arrays of dubious lifetimes/NULL-terminated arrays + pattern = "^(resolve_async|resolve_all_async)$" + ignore = true + +[[object]] +name = "OSTree.RepoFinderResult" +status = "generate" + [[object.function]] + # [IGNORE] array helper function + name = "freev" + ignore = true + + [[object.function]] + # [IGNORE] clone() should already be this + name = "dup" + ignore = true + +[[object]] +name = "OSTree.SePolicy" +status = "generate" +concurrency = "send" + [[object.function]] + # [IGNORE] has an unused raw pointer parameter + name = "fscreatecon_cleanup" + ignore = true + +[[object]] +name = "OSTree.Sign" +status = "generate" + [[object.function]] + # [IGNORE] these shouldn't be on this type, they belong to subclasses + pattern = "^(dummy_.+|ed25519_.+)$" + ignore = true + +[[object]] +name = "OSTree.Sysroot" +status = "generate" + [[object.function]] + name = "deploy_tree_with_options" + [[object.function.parameter]] + name = "opts" + const = true + + [[object.function]] + name = "stage_tree_with_options" + [[object.function.parameter]] + name = "opts" + const = true + + [[object.function]] + name = "write_deployments_with_options" + [[object.function.parameter]] + name = "opts" + const = true + + [[object.function]] + # [IGNORE] overlaps with repo() + name = "get_repo" + ignore = true + +[[object]] +name = "OSTree.*" +status = "generate" + [[object.function]] + # [MANUAL] probably can't be autogenerated because of the custom Checksum type + pattern = "^(checksum_file|checksum_file_async|checksum_file_at|checksum_file_from_input)$" + ignore = true + + [[object.function]] + # [IGNORE] low-level checksum functions, we have a custom checksum API + pattern = "^(cmp_checksum_bytes|checksum_from_bytes|checksum_to_bytes|checksum_inplace_from_bytes|checksum_inplace_to_bytes|checksum_b64_from_bytes|checksum_b64_to_bytes|checksum_b64_inplace_from_bytes|checksum_b64_inplace_to_bytes)$" + ignore = true + + [[object.function]] + # [IGNORE] needs custom handling to deal with its raw pointer parameter + name = "hash_object_name" + ignore = true + + [[object.function]] + # [IGNORE] private API + name = "cmd__private__" + ignore = true + + [[object.constant]] + # [IGNORE] version-dependent constants + pattern = "^(VERSION|VERSION_S|YEAR_VERSION|RELEASE_VERSION)$" + ignore = true + + [[object.constant]] + # [IGNORE] build-dependent constants + name = "BUILT_FEATURES" + ignore = true diff --git a/rust-bindings/gir-files/GLib-2.0.gir b/rust-bindings/gir-files/GLib-2.0.gir new file mode 100644 index 0000000000..0a894f03fd --- /dev/null +++ b/rust-bindings/gir-files/GLib-2.0.gir @@ -0,0 +1,55079 @@ +<?xml version="1.0"?> +<!-- This file was automatically generated from C sources - DO NOT EDIT! +To affect the contents of this file, edit the original C definitions, +and/or use gtk-doc annotations. --> +<repository xmlns="http://www.gtk.org/introspection/core/1.0" xmlns:c="http://www.gtk.org/introspection/c/1.0" xmlns:glib="http://www.gtk.org/introspection/glib/1.0" version="1.2"> + <package name="glib-2.0"/> + <c:include name="glib.h"/> + <namespace name="GLib" version="2.0" shared-library="libgobject-2.0.so.0,libglib-2.0.so.0" c:identifier-prefixes="G" c:symbol-prefixes="g,glib"> + <alias name="DateDay" c:type="GDateDay"> + <doc xml:space="preserve">Integer representing a day of the month; between 1 and 31. +#G_DATE_BAD_DAY represents an invalid day of the month.</doc> + <type name="guint8" c:type="guint8"/> + </alias> + <alias name="DateYear" c:type="GDateYear"> + <doc xml:space="preserve">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.</doc> + <type name="guint16" c:type="guint16"/> + </alias> + <alias name="MainContextPusher" c:type="GMainContextPusher"> + <doc xml:space="preserve">Opaque type. See g_main_context_pusher_new() for details.</doc> + <type name="none" c:type="void"/> + </alias> + <alias name="MutexLocker" c:type="GMutexLocker"> + <doc xml:space="preserve">Opaque type. See g_mutex_locker_new() for details.</doc> + <type name="none" c:type="void"/> + </alias> + <alias name="Pid" c:type="GPid"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="int"/> + </alias> + <alias name="Quark" c:type="GQuark"> + <doc xml:space="preserve">A GQuark is a non-zero integer which uniquely identifies a +particular string. A GQuark value of zero is associated to %NULL.</doc> + <type name="guint32" c:type="guint32"/> + </alias> + <alias name="RWLockReaderLocker" c:type="GRWLockReaderLocker"> + <doc xml:space="preserve">Opaque type. See g_rw_lock_reader_locker_new() for details.</doc> + <type name="none" c:type="void"/> + </alias> + <alias name="RWLockWriterLocker" c:type="GRWLockWriterLocker"> + <doc xml:space="preserve">Opaque type. See g_rw_lock_writer_locker_new() for details.</doc> + <type name="none" c:type="void"/> + </alias> + <alias name="RecMutexLocker" c:type="GRecMutexLocker"> + <doc xml:space="preserve">Opaque type. See g_rec_mutex_locker_new() for details.</doc> + <type name="none" c:type="void"/> + </alias> + <alias name="RefString" c:type="GRefString"> + <doc xml:space="preserve">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.</doc> + <type name="gchar" c:type="char"/> + </alias> + <alias name="Strv" c:type="GStrv"> + <doc xml:space="preserve">A typedef alias for gchar**. This is mostly useful when used together with +g_auto().</doc> + <type name="utf8" c:type="gchar**"/> + </alias> + <alias name="Time" c:type="GTime" deprecated="1" deprecated-version="2.62"> + <doc xml:space="preserve">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; +]|</doc> + <doc-deprecated xml:space="preserve">This is not [Y2038-safe](https://en.wikipedia.org/wiki/Year_2038_problem). + Use #GDateTime or #time_t instead.</doc-deprecated> + <type name="gint32" c:type="gint32"/> + </alias> + <alias name="TimeSpan" c:type="GTimeSpan"> + <doc xml:space="preserve">A value representing an interval of time, in microseconds.</doc> + <type name="gint64" c:type="gint64"/> + </alias> + <alias name="Type" c:type="GType"> + <type name="gsize" c:type="gsize"/> + </alias> + <function-macro name="ALIGNOF" c:identifier="G_ALIGNOF" version="2.60" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">a type-name</doc> + </parameter> + </parameters> + </function-macro> + <constant name="ANALYZER_ANALYZING" value="1" c:type="G_ANALYZER_ANALYZING"> + <type name="gint" c:type="gint"/> + </constant> + <function-macro name="APPROX_VALUE" c:identifier="G_APPROX_VALUE" version="2.58" introspectable="0"> + <doc xml:space="preserve">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</doc> + <parameters> + <parameter name="a"> + <doc xml:space="preserve">a numeric value</doc> + </parameter> + <parameter name="b"> + <doc xml:space="preserve">a numeric value</doc> + </parameter> + <parameter name="epsilon"> + <doc xml:space="preserve">a numeric value that expresses the tolerance between @a and @b</doc> + </parameter> + </parameters> + </function-macro> + <constant name="ASCII_DTOSTR_BUF_SIZE" value="39" c:type="G_ASCII_DTOSTR_BUF_SIZE"> + <doc xml:space="preserve">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)); +]|</doc> + <type name="gint" c:type="gint"/> + </constant> + <function-macro name="ATEXIT" c:identifier="g_ATEXIT" introspectable="0"> + <parameters> + <parameter name="proc"> + </parameter> + </parameters> + </function-macro> + <record name="Array" c:type="GArray" glib:type-name="GArray" glib:get-type="g_array_get_type" c:symbol-prefix="array"> + <doc xml:space="preserve">Contains the public fields of a GArray.</doc> + <field name="data" writable="1"> + <doc xml:space="preserve">a pointer to the element data. The data may be moved as + elements are added to the #GArray.</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="len" writable="1"> + <doc xml:space="preserve">the number of elements in the #GArray not including the + possible terminating zero element.</doc> + <type name="guint" c:type="guint"/> + </field> + <function name="append_vals" c:identifier="g_array_append_vals" introspectable="0"> + <doc xml:space="preserve">Adds @len elements onto the end of the array.</doc> + <return-value> + <doc xml:space="preserve">the #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to the elements to append to the end of the array</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements to append</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="binary_search" c:identifier="g_array_binary_search" version="2.62" introspectable="0"> + <doc xml:space="preserve">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); +... +]|</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @target is one of the elements of @array, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GArray.</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="target" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to the item to look up.</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="compare_func" transfer-ownership="none"> + <doc xml:space="preserve">A #GCompareFunc used to locate @target.</doc> + <type name="CompareFunc" c:type="GCompareFunc"/> + </parameter> + <parameter name="out_match_index" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">return location + for the index of the element, if found.</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </function> + <function name="copy" c:identifier="g_array_copy" version="2.62" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="container"> + <doc xml:space="preserve">A copy of @array.</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">A #GArray.</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + </parameters> + </function> + <function name="free" c:identifier="g_array_free" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the element data if @free_segment is %FALSE, otherwise + %NULL. The element data should be freed using g_free().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="free_segment" transfer-ownership="none"> + <doc xml:space="preserve">if %TRUE the actual element data is freed as well</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="get_element_size" c:identifier="g_array_get_element_size" version="2.22" introspectable="0"> + <doc xml:space="preserve">Gets the size of the elements in @array.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Size of each element, in bytes</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">A #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + </parameters> + </function> + <function name="insert_vals" c:identifier="g_array_insert_vals" introspectable="0"> + <doc xml:space="preserve">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. + +If @index_ is less than the array’s current length, new entries will be +inserted into the array, and the existing entries above @index_ will be moved +upwards. + +@data may be %NULL if (and only if) @len is zero. If @len is zero, this +function is a no-op.</doc> + <return-value> + <doc xml:space="preserve">the #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">the index to place the elements at</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to the elements to insert</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements to insert</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="new" c:identifier="g_array_new" introspectable="0"> + <doc xml:space="preserve">Creates a new #GArray with a reference count of 1.</doc> + <return-value> + <doc xml:space="preserve">the new #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="zero_terminated" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the array should have an extra element at + the end which is set to 0</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="clear_" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if #GArray elements should be automatically cleared + to 0 when they are allocated</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="element_size" transfer-ownership="none"> + <doc xml:space="preserve">the size of each element in bytes</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="prepend_vals" c:identifier="g_array_prepend_vals" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to the elements to prepend to the start of the array</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements to prepend, which may be zero</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="ref" c:identifier="g_array_ref" version="2.22" introspectable="0"> + <doc xml:space="preserve">Atomically increments the reference count of @array by one. +This function is thread-safe and may be called from any thread.</doc> + <return-value> + <doc xml:space="preserve">The passed in #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">A #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + </parameters> + </function> + <function name="remove_index" c:identifier="g_array_remove_index" introspectable="0"> + <doc xml:space="preserve">Removes the element at the given index from a #GArray. The following +elements are moved down one place.</doc> + <return-value> + <doc xml:space="preserve">the #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">the index of the element to remove</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="remove_index_fast" c:identifier="g_array_remove_index_fast" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value> + <doc xml:space="preserve">the #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a @GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">the index of the element to remove</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="remove_range" c:identifier="g_array_remove_range" version="2.4" introspectable="0"> + <doc xml:space="preserve">Removes the given number of elements starting at the given index +from a #GArray. The following elements are moved to close the gap.</doc> + <return-value> + <doc xml:space="preserve">the #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a @GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">the index of the first element to remove</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements to remove</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="set_clear_func" c:identifier="g_array_set_clear_func" version="2.32" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">A #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="clear_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">a function to clear an element of @array</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="set_size" c:identifier="g_array_set_size" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the new size of the #GArray</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="sized_new" c:identifier="g_array_sized_new" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the new #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="zero_terminated" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the array should have an extra element at + the end with all bits cleared</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="clear_" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if all bits in the array should be cleared to 0 on + allocation</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="element_size" transfer-ownership="none"> + <doc xml:space="preserve">size of each element in the array</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="reserved_size" transfer-ownership="none"> + <doc xml:space="preserve">number of elements preallocated</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="sort" c:identifier="g_array_sort" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="compare_func" transfer-ownership="none"> + <doc xml:space="preserve">comparison function</doc> + <type name="CompareFunc" c:type="GCompareFunc"/> + </parameter> + </parameters> + </function> + <function name="sort_with_data" c:identifier="g_array_sort_with_data" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="compare_func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">comparison function</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @compare_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="steal" c:identifier="g_array_steal" version="2.64" introspectable="0"> + <doc xml:space="preserve">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); +... +]|</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the element data, which should be + freed using g_free().</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GArray.</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="len" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">pointer to retrieve the number of + elements of the original array</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </function> + <function name="unref" c:identifier="g_array_unref" version="2.22" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">A #GArray</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + </parameters> + </function> + </record> + <bitfield name="AsciiType" c:type="GAsciiType"> + <member name="alnum" value="1" c:identifier="G_ASCII_ALNUM"> + </member> + <member name="alpha" value="2" c:identifier="G_ASCII_ALPHA"> + </member> + <member name="cntrl" value="4" c:identifier="G_ASCII_CNTRL"> + </member> + <member name="digit" value="8" c:identifier="G_ASCII_DIGIT"> + </member> + <member name="graph" value="16" c:identifier="G_ASCII_GRAPH"> + </member> + <member name="lower" value="32" c:identifier="G_ASCII_LOWER"> + </member> + <member name="print" value="64" c:identifier="G_ASCII_PRINT"> + </member> + <member name="punct" value="128" c:identifier="G_ASCII_PUNCT"> + </member> + <member name="space" value="256" c:identifier="G_ASCII_SPACE"> + </member> + <member name="upper" value="512" c:identifier="G_ASCII_UPPER"> + </member> + <member name="xdigit" value="1024" c:identifier="G_ASCII_XDIGIT"> + </member> + </bitfield> + <record name="AsyncQueue" c:type="GAsyncQueue" disguised="1"> + <doc xml:space="preserve">The GAsyncQueue struct is an opaque data structure which represents +an asynchronous queue. It should only be accessed through the +g_async_queue_* functions.</doc> + <method name="length" c:identifier="g_async_queue_length"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the length of the @queue</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue.</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="length_unlocked" c:identifier="g_async_queue_length_unlocked"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the length of the @queue.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="lock" c:identifier="g_async_queue_lock"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="pop" c:identifier="g_async_queue_pop"> + <doc xml:space="preserve">Pops data from the @queue. If @queue is empty, this function +blocks until data becomes available.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">data from the queue</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="pop_unlocked" c:identifier="g_async_queue_pop_unlocked"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">data from the queue.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="push" c:identifier="g_async_queue_push"> + <doc xml:space="preserve">Pushes the @data into the @queue. @data must not be %NULL.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">@data to push into the @queue</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="push_front" c:identifier="g_async_queue_push_front" version="2.46"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + <parameter name="item" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to push into the @queue</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="push_front_unlocked" c:identifier="g_async_queue_push_front_unlocked" version="2.46"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + <parameter name="item" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to push into the @queue</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="push_sorted" c:identifier="g_async_queue_push_sorted" version="2.10" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the @data to push into the @queue</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the #GCompareDataFunc is used to sort @queue</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @func.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="push_sorted_unlocked" c:identifier="g_async_queue_push_sorted_unlocked" version="2.10" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the @data to push into the @queue</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the #GCompareDataFunc is used to sort @queue</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @func.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="push_unlocked" c:identifier="g_async_queue_push_unlocked"> + <doc xml:space="preserve">Pushes the @data into the @queue. @data must not be %NULL. + +This function must be called while holding the @queue's lock.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">@data to push into the @queue</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_async_queue_ref" introspectable="0"> + <doc xml:space="preserve">Increases the reference count of the asynchronous @queue by 1. +You do not need to hold the lock to call this function.</doc> + <return-value> + <doc xml:space="preserve">the @queue that was passed in (since 2.6)</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="ref_unlocked" c:identifier="g_async_queue_ref_unlocked" deprecated="1" deprecated-version="2.8"> + <doc xml:space="preserve">Increases the reference count of the asynchronous @queue by 1.</doc> + <doc-deprecated xml:space="preserve">Reference counting is done atomically. +so g_async_queue_ref() can be used regardless of the @queue's +lock.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="remove" c:identifier="g_async_queue_remove" version="2.46"> + <doc xml:space="preserve">Remove an item from the queue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the item was removed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + <parameter name="item" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to remove from the @queue</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="remove_unlocked" c:identifier="g_async_queue_remove_unlocked" version="2.46"> + <doc xml:space="preserve">Remove an item from the queue. + +This function must be called while holding the @queue's lock.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the item was removed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + <parameter name="item" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to remove from the @queue</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="sort" c:identifier="g_async_queue_sort" version="2.10" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + <parameter name="func" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">the #GCompareDataFunc is used to sort @queue</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="sort_unlocked" c:identifier="g_async_queue_sort_unlocked" version="2.10" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + <parameter name="func" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">the #GCompareDataFunc is used to sort @queue</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="timed_pop" c:identifier="g_async_queue_timed_pop" deprecated="1"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">use g_async_queue_timeout_pop().</doc-deprecated> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">data from the queue or %NULL, when no data is + received before @end_time.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + <parameter name="end_time" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeVal, determining the final time</doc> + <type name="TimeVal" c:type="GTimeVal*"/> + </parameter> + </parameters> + </method> + <method name="timed_pop_unlocked" c:identifier="g_async_queue_timed_pop_unlocked" deprecated="1"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">use g_async_queue_timeout_pop_unlocked().</doc-deprecated> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">data from the queue or %NULL, when no data is + received before @end_time.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + <parameter name="end_time" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeVal, determining the final time</doc> + <type name="TimeVal" c:type="GTimeVal*"/> + </parameter> + </parameters> + </method> + <method name="timeout_pop" c:identifier="g_async_queue_timeout_pop"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">data from the queue or %NULL, when no data is + received before the timeout.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + <parameter name="timeout" transfer-ownership="none"> + <doc xml:space="preserve">the number of microseconds to wait</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + </parameters> + </method> + <method name="timeout_pop_unlocked" c:identifier="g_async_queue_timeout_pop_unlocked"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">data from the queue or %NULL, when no data is + received before the timeout.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + <parameter name="timeout" transfer-ownership="none"> + <doc xml:space="preserve">the number of microseconds to wait</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + </parameters> + </method> + <method name="try_pop" c:identifier="g_async_queue_try_pop"> + <doc xml:space="preserve">Tries to pop data from the @queue. If no data is available, +%NULL is returned.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">data from the queue or %NULL, when no data is + available immediately.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="try_pop_unlocked" c:identifier="g_async_queue_try_pop_unlocked"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">data from the queue or %NULL, when no data is + available immediately.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="unlock" c:identifier="g_async_queue_unlock"> + <doc xml:space="preserve">Releases the queue's lock. + +Calling this function when you have not acquired +the with g_async_queue_lock() leads to undefined +behaviour.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_async_queue_unref"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue.</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref_and_unlock" c:identifier="g_async_queue_unref_and_unlock" deprecated="1" deprecated-version="2.8"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Reference counting is done atomically. +so g_async_queue_unref() can be used regardless of the @queue's +lock.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncQueue</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </instance-parameter> + </parameters> + </method> + <function name="new" c:identifier="g_async_queue_new" introspectable="0"> + <doc xml:space="preserve">Creates a new asynchronous queue.</doc> + <return-value> + <doc xml:space="preserve">a new #GAsyncQueue. Free with g_async_queue_unref()</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </return-value> + </function> + <function name="new_full" c:identifier="g_async_queue_new_full" version="2.16" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">a new #GAsyncQueue. Free with g_async_queue_unref()</doc> + <type name="AsyncQueue" c:type="GAsyncQueue*"/> + </return-value> + <parameters> + <parameter name="item_free_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">function to free queue elements</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + </record> + <constant name="BIG_ENDIAN" value="4321" c:type="G_BIG_ENDIAN"> + <doc xml:space="preserve">Specifies one of the possible types of byte order. +See #G_BYTE_ORDER.</doc> + <type name="gint" c:type="gint"/> + </constant> + <record name="BookmarkFile" c:type="GBookmarkFile" disguised="1"> + <doc xml:space="preserve">The `GBookmarkFile` structure contains only +private data and should not be directly accessed.</doc> + <method name="add_application" c:identifier="g_bookmark_file_add_application" version="2.12"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the name of the application registering the bookmark + or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="exec" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">command line to be used to launch the bookmark or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="add_group" c:identifier="g_bookmark_file_add_group" version="2.12"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">the group name to be added</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="free" c:identifier="g_bookmark_file_free" version="2.12"> + <doc xml:space="preserve">Frees a #GBookmarkFile.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_added" c:identifier="g_bookmark_file_get_added" version="2.12" deprecated="1" deprecated-version="2.66" throws="1"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_bookmark_file_get_added_date_time() instead, as + `time_t` is deprecated due to the year 2038 problem.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a timestamp</doc> + <type name="glong" c:type="time_t"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_added_date_time" c:identifier="g_bookmark_file_get_added_date_time" version="2.66" throws="1"> + <doc xml:space="preserve">Gets the time the bookmark for @uri was added to @bookmark + +In the event the URI cannot be found, %NULL is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_app_info" c:identifier="g_bookmark_file_get_app_info" version="2.12" deprecated="1" deprecated-version="2.66" throws="1"> + <doc xml:space="preserve">Gets the registration information of @app_name for the bookmark for +@uri. See g_bookmark_file_set_application_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.</doc> + <doc-deprecated xml:space="preserve">Use g_bookmark_file_get_application_info() instead, as + `time_t` is deprecated due to the year 2038 problem.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">an application's name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="exec" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the command line of the application, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="count" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the registration count, or %NULL</doc> + <type name="guint" c:type="guint*"/> + </parameter> + <parameter name="stamp" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the last registration time, or %NULL</doc> + <type name="glong" c:type="time_t*"/> + </parameter> + </parameters> + </method> + <method name="get_application_info" c:identifier="g_bookmark_file_get_application_info" version="2.66" throws="1"> + <doc xml:space="preserve">Gets the registration information of @app_name for the bookmark for +@uri. See g_bookmark_file_set_application_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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">an application's name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="exec" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the command line of the application, or %NULL</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="count" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the registration count, or %NULL</doc> + <type name="guint" c:type="unsigned int*"/> + </parameter> + <parameter name="stamp" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the last registration time, or %NULL</doc> + <type name="DateTime" c:type="GDateTime**"/> + </parameter> + </parameters> + </method> + <method name="get_applications" c:identifier="g_bookmark_file_get_applications" version="2.12" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated %NULL-terminated array of strings. + Use g_strfreev() to free it.</doc> + <array length="1" zero-terminated="0" c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location of the length of the returned list, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_description" c:identifier="g_bookmark_file_get_description" version="2.12" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string or %NULL if the specified + URI cannot be found.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_groups" c:identifier="g_bookmark_file_get_groups" version="2.12" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated %NULL-terminated array of group names. + Use g_strfreev() to free it.</doc> + <array length="1" zero-terminated="0" c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the length of the returned string, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_icon" c:identifier="g_bookmark_file_get_icon" version="2.12" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the icon for the bookmark for the URI was found. + You should free the returned strings.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="href" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the icon's location or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="mime_type" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the icon's MIME type or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </method> + <method name="get_is_private" c:identifier="g_bookmark_file_get_is_private" version="2.12" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the private flag is set, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_mime_type" c:identifier="g_bookmark_file_get_mime_type" version="2.12" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string or %NULL if the specified + URI cannot be found.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_modified" c:identifier="g_bookmark_file_get_modified" version="2.12" deprecated="1" deprecated-version="2.66" throws="1"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_bookmark_file_get_modified_date_time() instead, as + `time_t` is deprecated due to the year 2038 problem.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a timestamp</doc> + <type name="glong" c:type="time_t"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_modified_date_time" c:identifier="g_bookmark_file_get_modified_date_time" version="2.66" throws="1"> + <doc xml:space="preserve">Gets the time when the bookmark for @uri was last modified. + +In the event the URI cannot be found, %NULL is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_size" c:identifier="g_bookmark_file_get_size" version="2.12"> + <doc xml:space="preserve">Gets the number of bookmarks inside @bookmark.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bookmarks</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_title" c:identifier="g_bookmark_file_get_title" version="2.12" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string or %NULL if the specified + URI cannot be found.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a valid URI or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_uris" c:identifier="g_bookmark_file_get_uris" version="2.12"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated %NULL-terminated array of strings. + Use g_strfreev() to free it.</doc> + <array length="0" zero-terminated="0" c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the number of returned URIs, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_visited" c:identifier="g_bookmark_file_get_visited" version="2.12" deprecated="1" deprecated-version="2.66" throws="1"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_bookmark_file_get_visited_date_time() instead, as + `time_t` is deprecated due to the year 2038 problem.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a timestamp.</doc> + <type name="glong" c:type="time_t"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_visited_date_time" c:identifier="g_bookmark_file_get_visited_date_time" version="2.66" throws="1"> + <doc xml:space="preserve">Gets the time the bookmark for @uri was last visited. + +In the event the URI cannot be found, %NULL is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="has_application" c:identifier="g_bookmark_file_has_application" version="2.12" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the application @name was found</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the application</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="has_group" c:identifier="g_bookmark_file_has_group" version="2.12" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @group was found.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">the group name to be searched</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="has_item" c:identifier="g_bookmark_file_has_item" version="2.12"> + <doc xml:space="preserve">Looks whether the desktop bookmark has an item with its URI set to @uri.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @uri is inside @bookmark, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="load_from_data" c:identifier="g_bookmark_file_load_from_data" version="2.12" throws="1"> + <doc xml:space="preserve">Loads a bookmark file from memory into an empty #GBookmarkFile +structure. If the object cannot be created then @error is set to a +#GBookmarkFileError.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a desktop bookmark could be loaded.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">an empty #GBookmarkFile struct</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">desktop bookmarks + loaded in memory</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @data in bytes</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <method name="load_from_data_dirs" c:identifier="g_bookmark_file_load_from_data_dirs" version="2.12" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a key file could be loaded, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a relative path to a filename to open and parse</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="full_path" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for a string + containing the full path of the file, or %NULL</doc> + <type name="filename" c:type="gchar**"/> + </parameter> + </parameters> + </method> + <method name="load_from_file" c:identifier="g_bookmark_file_load_from_file" version="2.12" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a desktop bookmark file could be loaded</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">an empty #GBookmarkFile struct</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">the path of a filename to load, in the + GLib file name encoding</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="move_item" c:identifier="g_bookmark_file_move_item" version="2.12" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the URI was successfully changed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="old_uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="new_uri" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a valid URI, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="remove_application" c:identifier="g_bookmark_file_remove_application" version="2.12" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the application was successfully removed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the application</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="remove_group" c:identifier="g_bookmark_file_remove_group" version="2.12" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @group was successfully removed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">the group name to be removed</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="remove_item" c:identifier="g_bookmark_file_remove_item" version="2.12" throws="1"> + <doc xml:space="preserve">Removes the bookmark for @uri from the bookmark file @bookmark.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the bookmark was removed successfully.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_added" c:identifier="g_bookmark_file_set_added" version="2.12" deprecated="1" deprecated-version="2.66"> + <doc xml:space="preserve">Sets the time the bookmark for @uri was added into @bookmark. + +If no bookmark for @uri is found then it is created.</doc> + <doc-deprecated xml:space="preserve">Use g_bookmark_file_set_added_date_time() instead, as + `time_t` is deprecated due to the year 2038 problem.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="added" transfer-ownership="none"> + <doc xml:space="preserve">a timestamp or -1 to use the current time</doc> + <type name="glong" c:type="time_t"/> + </parameter> + </parameters> + </method> + <method name="set_added_date_time" c:identifier="g_bookmark_file_set_added_date_time" version="2.66"> + <doc xml:space="preserve">Sets the time the bookmark for @uri was added into @bookmark. + +If no bookmark for @uri is found then it is created.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="added" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </parameter> + </parameters> + </method> + <method name="set_app_info" c:identifier="g_bookmark_file_set_app_info" version="2.12" deprecated="1" deprecated-version="2.66" throws="1"> + <doc xml:space="preserve">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_application_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.</doc> + <doc-deprecated xml:space="preserve">Use g_bookmark_file_set_application_info() instead, as + `time_t` is deprecated due to the year 2038 problem.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the application's meta-data was successfully + changed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">an application's name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="exec" transfer-ownership="none"> + <doc xml:space="preserve">an application's command line</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of registrations done for this application</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="stamp" transfer-ownership="none"> + <doc xml:space="preserve">the time of the last registration for this application</doc> + <type name="glong" c:type="time_t"/> + </parameter> + </parameters> + </method> + <method name="set_application_info" c:identifier="g_bookmark_file_set_application_info" version="2.66" throws="1"> + <doc xml:space="preserve">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_application_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 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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the application's meta-data was successfully + changed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">an application's name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="exec" transfer-ownership="none"> + <doc xml:space="preserve">an application's command line</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of registrations done for this application</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="stamp" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the time of the last registration for this application, + which may be %NULL if @count is 0</doc> + <type name="DateTime" c:type="GDateTime*"/> + </parameter> + </parameters> + </method> + <method name="set_description" c:identifier="g_bookmark_file_set_description" version="2.12"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a valid URI or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="description" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_groups" c:identifier="g_bookmark_file_set_groups" version="2.12"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">an item's URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="groups" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an array of + group names, or %NULL to remove all groups</doc> + <array length="2" zero-terminated="0" c:type="const gchar**"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">number of group name values in @groups</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <method name="set_icon" c:identifier="g_bookmark_file_set_icon" version="2.12"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="href" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the URI of the icon for the bookmark, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="mime_type" transfer-ownership="none"> + <doc xml:space="preserve">the MIME type of the icon for the bookmark</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_is_private" c:identifier="g_bookmark_file_set_is_private" version="2.12"> + <doc xml:space="preserve">Sets the private flag of the bookmark for @uri. + +If a bookmark for @uri cannot be found then it is created.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="is_private" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the bookmark should be marked as private</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_mime_type" c:identifier="g_bookmark_file_set_mime_type" version="2.12"> + <doc xml:space="preserve">Sets @mime_type as the MIME type of the bookmark for @uri. + +If a bookmark for @uri cannot be found then it is created.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="mime_type" transfer-ownership="none"> + <doc xml:space="preserve">a MIME type</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_modified" c:identifier="g_bookmark_file_set_modified" version="2.12" deprecated="1" deprecated-version="2.66"> + <doc xml:space="preserve">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_date_time().</doc> + <doc-deprecated xml:space="preserve">Use g_bookmark_file_set_modified_date_time() instead, as + `time_t` is deprecated due to the year 2038 problem.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="modified" transfer-ownership="none"> + <doc xml:space="preserve">a timestamp or -1 to use the current time</doc> + <type name="glong" c:type="time_t"/> + </parameter> + </parameters> + </method> + <method name="set_modified_date_time" c:identifier="g_bookmark_file_set_modified_date_time" version="2.66"> + <doc xml:space="preserve">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_date_time().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="modified" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </parameter> + </parameters> + </method> + <method name="set_title" c:identifier="g_bookmark_file_set_title" version="2.12"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a valid URI or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="title" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_visited" c:identifier="g_bookmark_file_set_visited" version="2.12" deprecated="1" deprecated-version="2.66"> + <doc xml:space="preserve">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_application_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.</doc> + <doc-deprecated xml:space="preserve">Use g_bookmark_file_set_visited_date_time() instead, as + `time_t` is deprecated due to the year 2038 problem.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="visited" transfer-ownership="none"> + <doc xml:space="preserve">a timestamp or -1 to use the current time</doc> + <type name="glong" c:type="time_t"/> + </parameter> + </parameters> + </method> + <method name="set_visited_date_time" c:identifier="g_bookmark_file_set_visited_date_time" version="2.66"> + <doc xml:space="preserve">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_application_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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="visited" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </parameter> + </parameters> + </method> + <method name="to_data" c:identifier="g_bookmark_file_to_data" version="2.12" throws="1"> + <doc xml:space="preserve">This function outputs @bookmark as a string.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + a newly allocated string holding the contents of the #GBookmarkFile</doc> + <array length="0" zero-terminated="0" c:type="gchar*"> + <type name="guint8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the length of the returned string, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="to_file" c:identifier="g_bookmark_file_to_file" version="2.12" throws="1"> + <doc xml:space="preserve">This function outputs @bookmark into a file. The write process is +guaranteed to be atomic by using g_file_set_contents() internally.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the file was successfully written.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bookmark" transfer-ownership="none"> + <doc xml:space="preserve">a #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </instance-parameter> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">path of the output file</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <function name="error_quark" c:identifier="g_bookmark_file_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="new" c:identifier="g_bookmark_file_new" version="2.12" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">an empty #GBookmarkFile</doc> + <type name="BookmarkFile" c:type="GBookmarkFile*"/> + </return-value> + </function> + </record> + <enumeration name="BookmarkFileError" c:type="GBookmarkFileError" glib:error-domain="g-bookmark-file-error-quark"> + <doc xml:space="preserve">Error codes returned by bookmark file parsing.</doc> + <member name="invalid_uri" value="0" c:identifier="G_BOOKMARK_FILE_ERROR_INVALID_URI"> + <doc xml:space="preserve">URI was ill-formed</doc> + </member> + <member name="invalid_value" value="1" c:identifier="G_BOOKMARK_FILE_ERROR_INVALID_VALUE"> + <doc xml:space="preserve">a requested field was not found</doc> + </member> + <member name="app_not_registered" value="2" c:identifier="G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED"> + <doc xml:space="preserve">a requested application did + not register a bookmark</doc> + </member> + <member name="uri_not_found" value="3" c:identifier="G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND"> + <doc xml:space="preserve">a requested URI was not found</doc> + </member> + <member name="read" value="4" c:identifier="G_BOOKMARK_FILE_ERROR_READ"> + <doc xml:space="preserve">document was ill formed</doc> + </member> + <member name="unknown_encoding" value="5" c:identifier="G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING"> + <doc xml:space="preserve">the text being parsed was + in an unknown encoding</doc> + </member> + <member name="write" value="6" c:identifier="G_BOOKMARK_FILE_ERROR_WRITE"> + <doc xml:space="preserve">an error occurred while writing</doc> + </member> + <member name="file_not_found" value="7" c:identifier="G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND"> + <doc xml:space="preserve">requested file was not found</doc> + </member> + </enumeration> + <record name="ByteArray" c:type="GByteArray" glib:type-name="GByteArray" glib:get-type="g_byte_array_get_type" c:symbol-prefix="byte_array"> + <doc xml:space="preserve">Contains the public fields of a GByteArray.</doc> + <field name="data" writable="1"> + <doc xml:space="preserve">a pointer to the element data. The data may be moved as + elements are added to the #GByteArray</doc> + <type name="guint8" c:type="guint8*"/> + </field> + <field name="len" writable="1"> + <doc xml:space="preserve">the number of elements in the #GByteArray</doc> + <type name="guint" c:type="guint"/> + </field> + <function name="append" c:identifier="g_byte_array_append" introspectable="0"> + <doc xml:space="preserve">Adds the given bytes to the end of the #GByteArray. +The array will grow in size automatically if necessary.</doc> + <return-value> + <doc xml:space="preserve">the #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">the byte data to be added</doc> + <type name="guint8" c:type="const guint8*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to add</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="free" c:identifier="g_byte_array_free"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the element data if @free_segment is %FALSE, otherwise + %NULL. The element data should be freed using g_free().</doc> + <type name="guint8" c:type="guint8*"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="free_segment" transfer-ownership="none"> + <doc xml:space="preserve">if %TRUE the actual byte data is freed as well</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="free_to_bytes" c:identifier="g_byte_array_free_to_bytes" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new immutable #GBytes representing same + byte data that was in the array</doc> + <type name="Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="full"> + <doc xml:space="preserve">a #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + </parameters> + </function> + <function name="new" c:identifier="g_byte_array_new"> + <doc xml:space="preserve">Creates a new #GByteArray with a reference count of 1.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </return-value> + </function> + <function name="new_take" c:identifier="g_byte_array_new_take" version="2.32"> + <doc xml:space="preserve">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(). + +Do not use it if @len is greater than %G_MAXUINT. #GByteArray +stores the length of its data in #guint, which may be shorter than +#gsize.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="full"> + <doc xml:space="preserve">byte data for the array</doc> + <array length="1" zero-terminated="0" c:type="guint8*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">length of @data</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="prepend" c:identifier="g_byte_array_prepend" introspectable="0"> + <doc xml:space="preserve">Adds the given data to the start of the #GByteArray. +The array will grow in size automatically if necessary.</doc> + <return-value> + <doc xml:space="preserve">the #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">the byte data to be added</doc> + <type name="guint8" c:type="const guint8*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to add</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="ref" c:identifier="g_byte_array_ref" version="2.22" introspectable="0"> + <doc xml:space="preserve">Atomically increments the reference count of @array by one. +This function is thread-safe and may be called from any thread.</doc> + <return-value> + <doc xml:space="preserve">The passed in #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">A #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + </parameters> + </function> + <function name="remove_index" c:identifier="g_byte_array_remove_index" introspectable="0"> + <doc xml:space="preserve">Removes the byte at the given index from a #GByteArray. +The following bytes are moved down one place.</doc> + <return-value> + <doc xml:space="preserve">the #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">the index of the byte to remove</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="remove_index_fast" c:identifier="g_byte_array_remove_index_fast" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value> + <doc xml:space="preserve">the #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">the index of the byte to remove</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="remove_range" c:identifier="g_byte_array_remove_range" version="2.4" introspectable="0"> + <doc xml:space="preserve">Removes the given number of bytes starting at the given index from a +#GByteArray. The following elements are moved to close the gap.</doc> + <return-value> + <doc xml:space="preserve">the #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a @GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">the index of the first byte to remove</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to remove</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="set_size" c:identifier="g_byte_array_set_size" introspectable="0"> + <doc xml:space="preserve">Sets the size of the #GByteArray, expanding it if necessary.</doc> + <return-value> + <doc xml:space="preserve">the #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the new size of the #GByteArray</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="sized_new" c:identifier="g_byte_array_sized_new" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the new #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="reserved_size" transfer-ownership="none"> + <doc xml:space="preserve">number of bytes preallocated</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="sort" c:identifier="g_byte_array_sort" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="compare_func" transfer-ownership="none"> + <doc xml:space="preserve">comparison function</doc> + <type name="CompareFunc" c:type="GCompareFunc"/> + </parameter> + </parameters> + </function> + <function name="sort_with_data" c:identifier="g_byte_array_sort_with_data" introspectable="0"> + <doc xml:space="preserve">Like g_byte_array_sort(), but the comparison function takes an extra +user data argument.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="compare_func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">comparison function</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @compare_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="steal" c:identifier="g_byte_array_steal" version="2.64"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the element data, which should be + freed using g_free().</doc> + <type name="guint8" c:type="guint8*"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray.</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="len" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">pointer to retrieve the number of + elements of the original array</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </function> + <function name="unref" c:identifier="g_byte_array_unref" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">A #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + </parameters> + </function> + </record> + <record name="Bytes" c:type="GBytes" version="2.32" glib:type-name="GBytes" glib:get-type="g_bytes_get_type" c:symbol-prefix="bytes"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_bytes_new" version="2.32"> + <doc xml:space="preserve">Creates a new #GBytes from @data. + +@data is copied. If @size is 0, @data may be %NULL.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GBytes</doc> + <type name="Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve"> + the data to be used for the bytes</doc> + <array length="1" zero-terminated="0" c:type="gconstpointer"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">the size of @data</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_static" c:identifier="g_bytes_new_static" version="2.32" introspectable="0"> + <doc xml:space="preserve">Creates a new #GBytes from static data. + +@data must be static (ie: never modified or freed). It may be %NULL if @size +is 0.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GBytes</doc> + <type name="Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="full" nullable="1" allow-none="1"> + <doc xml:space="preserve"> + the data to be used for the bytes</doc> + <array length="1" zero-terminated="0" c:type="gconstpointer"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">the size of @data</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_take" c:identifier="g_bytes_new_take" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GBytes</doc> + <type name="Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="full" nullable="1" allow-none="1"> + <doc xml:space="preserve"> + the data to be used for the bytes</doc> + <array length="1" zero-terminated="0" c:type="gpointer"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">the size of @data</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_with_free_func" c:identifier="g_bytes_new_with_free_func" version="2.32" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GBytes</doc> + <type name="Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve"> + the data to be used for the bytes</doc> + <array length="1" zero-terminated="0" c:type="gconstpointer"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">the size of @data</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="free_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">the function to call to release the data</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @free_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </constructor> + <method name="compare" c:identifier="g_bytes_compare" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="bytes1" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GBytes</doc> + <type name="Bytes" c:type="gconstpointer"/> + </instance-parameter> + <parameter name="bytes2" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GBytes to compare with @bytes1</doc> + <type name="Bytes" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="equal" c:identifier="g_bytes_equal" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the two keys match.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="bytes1" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GBytes</doc> + <type name="Bytes" c:type="gconstpointer"/> + </instance-parameter> + <parameter name="bytes2" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GBytes to compare with @bytes1</doc> + <type name="Bytes" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="get_data" c:identifier="g_bytes_get_data" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve"> + a pointer to the byte data, or %NULL</doc> + <array length="0" zero-terminated="0" c:type="gconstpointer"> + <type name="guint8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="bytes" transfer-ownership="none"> + <doc xml:space="preserve">a #GBytes</doc> + <type name="Bytes" c:type="GBytes*"/> + </instance-parameter> + <parameter name="size" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to return size of byte data</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_size" c:identifier="g_bytes_get_size" version="2.32"> + <doc xml:space="preserve">Get the size of the byte data in the #GBytes. + +This function will always return the same value for a given #GBytes.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the size</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="bytes" transfer-ownership="none"> + <doc xml:space="preserve">a #GBytes</doc> + <type name="Bytes" c:type="GBytes*"/> + </instance-parameter> + </parameters> + </method> + <method name="hash" c:identifier="g_bytes_hash" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a hash value corresponding to the key.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="bytes" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GBytes key</doc> + <type name="Bytes" c:type="gconstpointer"/> + </instance-parameter> + </parameters> + </method> + <method name="new_from_bytes" c:identifier="g_bytes_new_from_bytes" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GBytes</doc> + <type name="Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <instance-parameter name="bytes" transfer-ownership="none"> + <doc xml:space="preserve">a #GBytes</doc> + <type name="Bytes" c:type="GBytes*"/> + </instance-parameter> + <parameter name="offset" transfer-ownership="none"> + <doc xml:space="preserve">offset which subsection starts at</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">length of subsection</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_bytes_ref" version="2.32"> + <doc xml:space="preserve">Increase the reference count on @bytes.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the #GBytes</doc> + <type name="Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <instance-parameter name="bytes" transfer-ownership="none"> + <doc xml:space="preserve">a #GBytes</doc> + <type name="Bytes" c:type="GBytes*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_bytes_unref" version="2.32"> + <doc xml:space="preserve">Releases a reference on @bytes. This may result in the bytes being +freed. If @bytes is %NULL, it will return immediately.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="bytes" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GBytes</doc> + <type name="Bytes" c:type="GBytes*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref_to_array" c:identifier="g_bytes_unref_to_array" version="2.32"> + <doc xml:space="preserve">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. + +Do not use it if @bytes contains more than %G_MAXUINT +bytes. #GByteArray stores the length of its data in #guint, which +may be shorter than #gsize, that @bytes is using.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new mutable #GByteArray containing the same byte data</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="bytes" transfer-ownership="full"> + <doc xml:space="preserve">a #GBytes</doc> + <type name="Bytes" c:type="GBytes*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref_to_data" c:identifier="g_bytes_unref_to_data" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to the same byte data, which should be + freed with g_free()</doc> + <array length="0" zero-terminated="0" c:type="gpointer"> + <type name="guint8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="bytes" transfer-ownership="full"> + <doc xml:space="preserve">a #GBytes</doc> + <type name="Bytes" c:type="GBytes*"/> + </instance-parameter> + <parameter name="size" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">location to place the length of the returned data</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + </record> + <function-macro name="CHECK_VERSION" c:identifier="GLIB_CHECK_VERSION" introspectable="0"> + <doc xml:space="preserve">Checks the version of the GLib library that is being compiled +against. See glib_check_version() for a runtime check.</doc> + <parameters> + <parameter name="major"> + <doc xml:space="preserve">the major version to check for</doc> + </parameter> + <parameter name="minor"> + <doc xml:space="preserve">the minor version to check for</doc> + </parameter> + <parameter name="micro"> + <doc xml:space="preserve">the micro version to check for</doc> + </parameter> + </parameters> + </function-macro> + <constant name="CSET_A_2_Z" value="ABCDEFGHIJKLMNOPQRSTUVWXYZ" c:type="G_CSET_A_2_Z"> + <doc xml:space="preserve">The set of uppercase ASCII alphabet characters. +Used for specifying valid identifier characters +in #GScannerConfig.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="CSET_DIGITS" value="0123456789" c:type="G_CSET_DIGITS"> + <doc xml:space="preserve">The set of ASCII digits. +Used for specifying valid identifier characters +in #GScannerConfig.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="CSET_a_2_z" value="abcdefghijklmnopqrstuvwxyz" c:type="G_CSET_a_2_z"> + <doc xml:space="preserve">The set of lowercase ASCII alphabet characters. +Used for specifying valid identifier characters +in #GScannerConfig.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <record name="Checksum" c:type="GChecksum" version="2.16" glib:type-name="GChecksum" glib:get-type="g_checksum_get_type" c:symbol-prefix="checksum"> + <doc xml:space="preserve">An opaque structure representing a checksumming operation. +To create a new GChecksum, use g_checksum_new(). To free +a GChecksum, use g_checksum_free().</doc> + <constructor name="new" c:identifier="g_checksum_new" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the newly created #GChecksum, or %NULL. + Use g_checksum_free() to free the memory allocated by it.</doc> + <type name="Checksum" c:type="GChecksum*"/> + </return-value> + <parameters> + <parameter name="checksum_type" transfer-ownership="none"> + <doc xml:space="preserve">the desired type of checksum</doc> + <type name="ChecksumType" c:type="GChecksumType"/> + </parameter> + </parameters> + </constructor> + <method name="copy" c:identifier="g_checksum_copy" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the copy of the passed #GChecksum. Use + g_checksum_free() when finished using it.</doc> + <type name="Checksum" c:type="GChecksum*"/> + </return-value> + <parameters> + <instance-parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve">the #GChecksum to copy</doc> + <type name="Checksum" c:type="const GChecksum*"/> + </instance-parameter> + </parameters> + </method> + <method name="free" c:identifier="g_checksum_free" version="2.16"> + <doc xml:space="preserve">Frees the memory allocated for @checksum.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve">a #GChecksum</doc> + <type name="Checksum" c:type="GChecksum*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_digest" c:identifier="g_checksum_get_digest" version="2.16" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve">a #GChecksum</doc> + <type name="Checksum" c:type="GChecksum*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">output buffer</doc> + <array length="1" zero-terminated="0" c:type="guint8*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="digest_len" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">an inout parameter. The caller initializes it to the size of @buffer. + After the call it contains the length of the digest.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_string" c:identifier="g_checksum_get_string" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the hexadecimal representation of the checksum. The + returned string is owned by the checksum and should not be modified + or freed.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve">a #GChecksum</doc> + <type name="Checksum" c:type="GChecksum*"/> + </instance-parameter> + </parameters> + </method> + <method name="reset" c:identifier="g_checksum_reset" version="2.18"> + <doc xml:space="preserve">Resets the state of the @checksum back to its initial state.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve">the #GChecksum to reset</doc> + <type name="Checksum" c:type="GChecksum*"/> + </instance-parameter> + </parameters> + </method> + <method name="update" c:identifier="g_checksum_update" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve">a #GChecksum</doc> + <type name="Checksum" c:type="GChecksum*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">buffer used to compute the checksum</doc> + <array length="1" zero-terminated="0" c:type="const guchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">size of the buffer, or -1 if it is a null-terminated string.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </method> + <function name="type_get_length" c:identifier="g_checksum_type_get_length" version="2.16"> + <doc xml:space="preserve">Gets the length in bytes of digests of type @checksum_type</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the checksum length, or -1 if @checksum_type is +not supported.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="checksum_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GChecksumType</doc> + <type name="ChecksumType" c:type="GChecksumType"/> + </parameter> + </parameters> + </function> + </record> + <enumeration name="ChecksumType" version="2.16" c:type="GChecksumType"> + <doc xml:space="preserve">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.</doc> + <member name="md5" value="0" c:identifier="G_CHECKSUM_MD5"> + <doc xml:space="preserve">Use the MD5 hashing algorithm</doc> + </member> + <member name="sha1" value="1" c:identifier="G_CHECKSUM_SHA1"> + <doc xml:space="preserve">Use the SHA-1 hashing algorithm</doc> + </member> + <member name="sha256" value="2" c:identifier="G_CHECKSUM_SHA256"> + <doc xml:space="preserve">Use the SHA-256 hashing algorithm</doc> + </member> + <member name="sha512" value="3" c:identifier="G_CHECKSUM_SHA512"> + <doc xml:space="preserve">Use the SHA-512 hashing algorithm (Since: 2.36)</doc> + </member> + <member name="sha384" value="4" c:identifier="G_CHECKSUM_SHA384"> + <doc xml:space="preserve">Use the SHA-384 hashing algorithm (Since: 2.51)</doc> + </member> + </enumeration> + <callback name="ChildWatchFunc" c:type="GChildWatchFunc"> + <doc xml:space="preserve">Prototype of a #GChildWatchSource callback, called when a child +process has exited. To interpret @status, see the documentation +for g_spawn_check_exit_status().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="pid" transfer-ownership="none"> + <doc xml:space="preserve">the process id of the child process</doc> + <type name="Pid" c:type="GPid"/> + </parameter> + <parameter name="status" transfer-ownership="none"> + <doc xml:space="preserve">Status information about the child process, encoded + in a platform-specific manner</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">user data passed to g_child_watch_add()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="ClearHandleFunc" c:type="GClearHandleFunc" version="2.56"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="handle_id" transfer-ownership="none"> + <doc xml:space="preserve">the handle ID to clear</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </callback> + <callback name="CompareDataFunc" c:type="GCompareDataFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">negative value if @a < @b; zero if @a = @b; positive + value if @a > @b</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="a" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a value</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="b" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a value to compare with</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">user data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="CompareFunc" c:type="GCompareFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">negative value if @a < @b; zero if @a = @b; positive + value if @a > @b</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="a" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a value</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="b" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a value to compare with</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </callback> + <record name="Cond" c:type="GCond"> + <doc xml:space="preserve">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.</doc> + <field name="p" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="i" readable="0" private="1"> + <array zero-terminated="0" fixed-size="2"> + <type name="guint" c:type="guint"/> + </array> + </field> + <method name="broadcast" c:identifier="g_cond_broadcast"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cond" transfer-ownership="none"> + <doc xml:space="preserve">a #GCond</doc> + <type name="Cond" c:type="GCond*"/> + </instance-parameter> + </parameters> + </method> + <method name="clear" c:identifier="g_cond_clear" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cond" transfer-ownership="none"> + <doc xml:space="preserve">an initialised #GCond</doc> + <type name="Cond" c:type="GCond*"/> + </instance-parameter> + </parameters> + </method> + <method name="init" c:identifier="g_cond_init" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cond" transfer-ownership="none"> + <doc xml:space="preserve">an uninitialized #GCond</doc> + <type name="Cond" c:type="GCond*"/> + </instance-parameter> + </parameters> + </method> + <method name="signal" c:identifier="g_cond_signal"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cond" transfer-ownership="none"> + <doc xml:space="preserve">a #GCond</doc> + <type name="Cond" c:type="GCond*"/> + </instance-parameter> + </parameters> + </method> + <method name="wait" c:identifier="g_cond_wait"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cond" transfer-ownership="none"> + <doc xml:space="preserve">a #GCond</doc> + <type name="Cond" c:type="GCond*"/> + </instance-parameter> + <parameter name="mutex" transfer-ownership="none"> + <doc xml:space="preserve">a #GMutex that is currently locked</doc> + <type name="Mutex" c:type="GMutex*"/> + </parameter> + </parameters> + </method> + <method name="wait_until" c:identifier="g_cond_wait_until" version="2.32"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on a signal, %FALSE on a timeout</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="cond" transfer-ownership="none"> + <doc xml:space="preserve">a #GCond</doc> + <type name="Cond" c:type="GCond*"/> + </instance-parameter> + <parameter name="mutex" transfer-ownership="none"> + <doc xml:space="preserve">a #GMutex that is currently locked</doc> + <type name="Mutex" c:type="GMutex*"/> + </parameter> + <parameter name="end_time" transfer-ownership="none"> + <doc xml:space="preserve">the monotonic time to wait until</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + </parameters> + </method> + </record> + <enumeration name="ConvertError" c:type="GConvertError" glib:error-domain="g_convert_error"> + <doc xml:space="preserve">Error codes returned by character set conversion routines.</doc> + <member name="no_conversion" value="0" c:identifier="G_CONVERT_ERROR_NO_CONVERSION"> + <doc xml:space="preserve">Conversion between the requested character + sets is not supported.</doc> + </member> + <member name="illegal_sequence" value="1" c:identifier="G_CONVERT_ERROR_ILLEGAL_SEQUENCE"> + <doc xml:space="preserve">Invalid byte sequence in conversion input; + or the character sequence could not be represented in the target + character set.</doc> + </member> + <member name="failed" value="2" c:identifier="G_CONVERT_ERROR_FAILED"> + <doc xml:space="preserve">Conversion failed for some reason.</doc> + </member> + <member name="partial_input" value="3" c:identifier="G_CONVERT_ERROR_PARTIAL_INPUT"> + <doc xml:space="preserve">Partial character sequence at end of input.</doc> + </member> + <member name="bad_uri" value="4" c:identifier="G_CONVERT_ERROR_BAD_URI"> + <doc xml:space="preserve">URI is invalid.</doc> + </member> + <member name="not_absolute_path" value="5" c:identifier="G_CONVERT_ERROR_NOT_ABSOLUTE_PATH"> + <doc xml:space="preserve">Pathname is not an absolute path.</doc> + </member> + <member name="no_memory" value="6" c:identifier="G_CONVERT_ERROR_NO_MEMORY"> + <doc xml:space="preserve">No memory available. Since: 2.40</doc> + </member> + <member name="embedded_nul" value="7" c:identifier="G_CONVERT_ERROR_EMBEDDED_NUL"> + <doc xml:space="preserve">An embedded NUL character is present in + conversion output where a NUL-terminated string is expected. + Since: 2.56</doc> + </member> + </enumeration> + <callback name="CopyFunc" c:type="GCopyFunc" version="2.4"> + <doc xml:space="preserve">A function of this signature is used to copy the node data +when doing a deep-copy of a tree.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A pointer to the copy</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="src" transfer-ownership="none"> + <doc xml:space="preserve">A pointer to the data which should be copied</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Additional data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <constant name="DATALIST_FLAGS_MASK" value="3" c:type="G_DATALIST_FLAGS_MASK"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="DATE_BAD_DAY" value="0" c:type="G_DATE_BAD_DAY"> + <doc xml:space="preserve">Represents an invalid #GDateDay.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="DATE_BAD_JULIAN" value="0" c:type="G_DATE_BAD_JULIAN"> + <doc xml:space="preserve">Represents an invalid Julian day number.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="DATE_BAD_YEAR" value="0" c:type="G_DATE_BAD_YEAR"> + <doc xml:space="preserve">Represents an invalid year.</doc> + <type name="gint" c:type="gint"/> + </constant> + <function-macro name="DEFINE_AUTOPTR_CLEANUP_FUNC" c:identifier="G_DEFINE_AUTOPTR_CLEANUP_FUNC" version="2.44" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TypeName"> + <doc xml:space="preserve">a type name to define a g_autoptr() cleanup function for</doc> + </parameter> + <parameter name="func"> + <doc xml:space="preserve">the cleanup function</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_AUTO_CLEANUP_CLEAR_FUNC" c:identifier="G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC" version="2.44" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TypeName"> + <doc xml:space="preserve">a type name to define a g_auto() cleanup function for</doc> + </parameter> + <parameter name="func"> + <doc xml:space="preserve">the clear function</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_AUTO_CLEANUP_FREE_FUNC" c:identifier="G_DEFINE_AUTO_CLEANUP_FREE_FUNC" version="2.44" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TypeName"> + <doc xml:space="preserve">a type name to define a g_auto() cleanup function for</doc> + </parameter> + <parameter name="func"> + <doc xml:space="preserve">the free function</doc> + </parameter> + <parameter name="none"> + <doc xml:space="preserve">the "none" value for the type</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_QUARK" c:identifier="G_DEFINE_QUARK" version="2.34" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="QN"> + <doc xml:space="preserve">the name to return a #GQuark for</doc> + </parameter> + <parameter name="q_n"> + <doc xml:space="preserve">prefix for the function name</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_26_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_26_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_28_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_28_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_30_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_30_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_32_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_32_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_34_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_34_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_36_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_36_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_38_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_38_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_40_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_40_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_42_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_42_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_44_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_44_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_46_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_46_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_48_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_48_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_50_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_50_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_52_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_52_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_54_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_54_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_56_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_56_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_58_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_58_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_60_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_60_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_62_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_62_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_64_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_64_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_ENUMERATOR_IN_2_66_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_66_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_FOR" c:identifier="G_DEPRECATED_FOR" version="2.32" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <parameters> + <parameter name="f"> + <doc xml:space="preserve">the name of the function that this function was deprecated for</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_26_FOR" c:identifier="GLIB_DEPRECATED_IN_2_26_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_28_FOR" c:identifier="GLIB_DEPRECATED_IN_2_28_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_30_FOR" c:identifier="GLIB_DEPRECATED_IN_2_30_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_32_FOR" c:identifier="GLIB_DEPRECATED_IN_2_32_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_34_FOR" c:identifier="GLIB_DEPRECATED_IN_2_34_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_36_FOR" c:identifier="GLIB_DEPRECATED_IN_2_36_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_38_FOR" c:identifier="GLIB_DEPRECATED_IN_2_38_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_40_FOR" c:identifier="GLIB_DEPRECATED_IN_2_40_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_42_FOR" c:identifier="GLIB_DEPRECATED_IN_2_42_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_44_FOR" c:identifier="GLIB_DEPRECATED_IN_2_44_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_46_FOR" c:identifier="GLIB_DEPRECATED_IN_2_46_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_48_FOR" c:identifier="GLIB_DEPRECATED_IN_2_48_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_50_FOR" c:identifier="GLIB_DEPRECATED_IN_2_50_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_52_FOR" c:identifier="GLIB_DEPRECATED_IN_2_52_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_54_FOR" c:identifier="GLIB_DEPRECATED_IN_2_54_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_56_FOR" c:identifier="GLIB_DEPRECATED_IN_2_56_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_58_FOR" c:identifier="GLIB_DEPRECATED_IN_2_58_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_60_FOR" c:identifier="GLIB_DEPRECATED_IN_2_60_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_62_FOR" c:identifier="GLIB_DEPRECATED_IN_2_62_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_64_FOR" c:identifier="GLIB_DEPRECATED_IN_2_64_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_IN_2_66_FOR" c:identifier="GLIB_DEPRECATED_IN_2_66_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_FOR" c:identifier="GLIB_DEPRECATED_MACRO_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_26_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_26_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_28_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_28_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_30_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_30_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_32_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_32_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_34_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_34_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_36_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_36_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_38_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_38_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_40_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_40_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_42_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_42_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_44_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_44_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_46_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_46_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_48_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_48_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_50_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_50_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_52_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_52_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_54_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_54_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_56_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_56_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_58_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_58_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_60_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_60_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_62_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_62_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_64_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_64_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_MACRO_IN_2_66_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_66_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_FOR" c:identifier="GLIB_DEPRECATED_TYPE_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_26_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_26_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_28_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_28_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_30_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_30_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_32_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_32_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_34_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_34_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_36_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_36_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_38_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_38_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_40_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_40_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_42_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_42_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_44_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_44_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_46_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_46_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_48_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_48_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_50_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_50_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_52_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_52_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_54_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_54_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_56_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_56_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_58_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_58_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_60_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_60_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_62_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_62_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_64_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_64_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEPRECATED_TYPE_IN_2_66_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_66_FOR" introspectable="0"> + <parameters> + <parameter name="f"> + </parameter> + </parameters> + </function-macro> + <constant name="DIR_SEPARATOR" value="47" c:type="G_DIR_SEPARATOR"> + <doc xml:space="preserve">The directory separator character. +This is '/' on UNIX machines and '\' under Windows.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="DIR_SEPARATOR_S" value="/" c:type="G_DIR_SEPARATOR_S"> + <doc xml:space="preserve">The directory separator as a string. +This is "/" on UNIX machines and "\" under Windows.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <record name="Data" c:type="GData" disguised="1"> + <doc xml:space="preserve">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.</doc> + </record> + <callback name="DataForeachFunc" c:type="GDataForeachFunc"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="key_id" transfer-ownership="none"> + <doc xml:space="preserve">the #GQuark id to identifying the data element.</doc> + <type name="Quark" c:type="GQuark"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data element.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">user data passed to g_dataset_foreach().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="Date" c:type="GDate" glib:type-name="GDate" glib:get-type="g_date_get_type" c:symbol-prefix="date"> + <doc xml:space="preserve">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 safe. 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.</doc> + <field name="julian_days" writable="1" bits="32"> + <doc xml:space="preserve">the Julian representation of the date</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="julian" writable="1" bits="1"> + <doc xml:space="preserve">this bit is set if @julian_days is valid</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="dmy" writable="1" bits="1"> + <doc xml:space="preserve">this is set if @day, @month and @year are valid</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="day" writable="1" bits="6"> + <doc xml:space="preserve">the day of the day-month-year representation of the date, + as a number between 1 and 31</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="month" writable="1" bits="4"> + <doc xml:space="preserve">the day of the day-month-year representation of the date, + as a number between 1 and 12</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="year" writable="1" bits="16"> + <doc xml:space="preserve">the day of the day-month-year representation of the date</doc> + <type name="guint" c:type="guint"/> + </field> + <constructor name="new" c:identifier="g_date_new"> + <doc xml:space="preserve">Allocates a #GDate and initializes +it to a safe 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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated #GDate</doc> + <type name="Date" c:type="GDate*"/> + </return-value> + </constructor> + <constructor name="new_dmy" c:identifier="g_date_new_dmy"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated #GDate initialized with @day, @month, and @year</doc> + <type name="Date" c:type="GDate*"/> + </return-value> + <parameters> + <parameter name="day" transfer-ownership="none"> + <doc xml:space="preserve">day of the month</doc> + <type name="DateDay" c:type="GDateDay"/> + </parameter> + <parameter name="month" transfer-ownership="none"> + <doc xml:space="preserve">month of the year</doc> + <type name="DateMonth" c:type="GDateMonth"/> + </parameter> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">year</doc> + <type name="DateYear" c:type="GDateYear"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_julian" c:identifier="g_date_new_julian"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated #GDate initialized with @julian_day</doc> + <type name="Date" c:type="GDate*"/> + </return-value> + <parameters> + <parameter name="julian_day" transfer-ownership="none"> + <doc xml:space="preserve">days since January 1, Year 1</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + </parameters> + </constructor> + <method name="add_days" c:identifier="g_date_add_days"> + <doc xml:space="preserve">Increments a date some number of days. +To move forward by weeks, add weeks*7 days. +The date must be valid.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to increment</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="n_days" transfer-ownership="none"> + <doc xml:space="preserve">number of days to move the date forward</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="add_months" c:identifier="g_date_add_months"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to increment</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="n_months" transfer-ownership="none"> + <doc xml:space="preserve">number of months to move forward</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="add_years" c:identifier="g_date_add_years"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to increment</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="n_years" transfer-ownership="none"> + <doc xml:space="preserve">number of years to move forward</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="clamp" c:identifier="g_date_clamp"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to clamp</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="min_date" transfer-ownership="none"> + <doc xml:space="preserve">minimum accepted value for @date</doc> + <type name="Date" c:type="const GDate*"/> + </parameter> + <parameter name="max_date" transfer-ownership="none"> + <doc xml:space="preserve">maximum accepted value for @date</doc> + <type name="Date" c:type="const GDate*"/> + </parameter> + </parameters> + </method> + <method name="clear" c:identifier="g_date_clear"> + <doc xml:space="preserve">Initializes one or more #GDate structs to a safe 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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">pointer to one or more dates to clear</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="n_dates" transfer-ownership="none"> + <doc xml:space="preserve">number of dates to clear</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="compare" c:identifier="g_date_compare"> + <doc xml:space="preserve">qsort()-style comparison function for dates. +Both dates must be valid.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">0 for equal, less than zero if @lhs is less than @rhs, + greater than zero if @lhs is greater than @rhs</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="lhs" transfer-ownership="none"> + <doc xml:space="preserve">first date to compare</doc> + <type name="Date" c:type="const GDate*"/> + </instance-parameter> + <parameter name="rhs" transfer-ownership="none"> + <doc xml:space="preserve">second date to compare</doc> + <type name="Date" c:type="const GDate*"/> + </parameter> + </parameters> + </method> + <method name="copy" c:identifier="g_date_copy" version="2.56"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated #GDate initialized from @date</doc> + <type name="Date" c:type="GDate*"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to copy</doc> + <type name="Date" c:type="const GDate*"/> + </instance-parameter> + </parameters> + </method> + <method name="days_between" c:identifier="g_date_days_between"> + <doc xml:space="preserve">Computes the number of days between two dates. +If @date2 is prior to @date1, the returned value is negative. +Both dates must be valid.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of days between @date1 and @date2</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="date1" transfer-ownership="none"> + <doc xml:space="preserve">the first date</doc> + <type name="Date" c:type="const GDate*"/> + </instance-parameter> + <parameter name="date2" transfer-ownership="none"> + <doc xml:space="preserve">the second date</doc> + <type name="Date" c:type="const GDate*"/> + </parameter> + </parameters> + </method> + <method name="free" c:identifier="g_date_free"> + <doc xml:space="preserve">Frees a #GDate returned from g_date_new().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to free</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_day" c:identifier="g_date_get_day"> + <doc xml:space="preserve">Returns the day of the month. The date must be valid.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">day of the month</doc> + <type name="DateDay" c:type="GDateDay"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to extract the day of the month from</doc> + <type name="Date" c:type="const GDate*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_day_of_year" c:identifier="g_date_get_day_of_year"> + <doc xml:space="preserve">Returns the day of the year, where Jan 1 is the first day of the +year. The date must be valid.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">day of the year</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to extract day of year from</doc> + <type name="Date" c:type="const GDate*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_iso8601_week_of_year" c:identifier="g_date_get_iso8601_week_of_year" version="2.6"> + <doc xml:space="preserve">Returns the week of the year, where weeks are interpreted according +to ISO 8601.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">ISO 8601 week number of the year.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GDate</doc> + <type name="Date" c:type="const GDate*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_julian" c:identifier="g_date_get_julian"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Julian day</doc> + <type name="guint32" c:type="guint32"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to extract the Julian day from</doc> + <type name="Date" c:type="const GDate*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_monday_week_of_year" c:identifier="g_date_get_monday_week_of_year"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">week of the year</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate</doc> + <type name="Date" c:type="const GDate*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_month" c:identifier="g_date_get_month"> + <doc xml:space="preserve">Returns the month of the year. The date must be valid.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">month of the year as a #GDateMonth</doc> + <type name="DateMonth" c:type="GDateMonth"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to get the month from</doc> + <type name="Date" c:type="const GDate*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_sunday_week_of_year" c:identifier="g_date_get_sunday_week_of_year"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">week number</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate</doc> + <type name="Date" c:type="const GDate*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_weekday" c:identifier="g_date_get_weekday"> + <doc xml:space="preserve">Returns the day of the week for a #GDate. The date must be valid.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">day of the week as a #GDateWeekday.</doc> + <type name="DateWeekday" c:type="GDateWeekday"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate</doc> + <type name="Date" c:type="const GDate*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_year" c:identifier="g_date_get_year"> + <doc xml:space="preserve">Returns the year of a #GDate. The date must be valid.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">year in which the date falls</doc> + <type name="DateYear" c:type="GDateYear"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate</doc> + <type name="Date" c:type="const GDate*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_first_of_month" c:identifier="g_date_is_first_of_month"> + <doc xml:space="preserve">Returns %TRUE if the date is on the first of a month. +The date must be valid.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the date is the first of the month</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to check</doc> + <type name="Date" c:type="const GDate*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_last_of_month" c:identifier="g_date_is_last_of_month"> + <doc xml:space="preserve">Returns %TRUE if the date is the last day of the month. +The date must be valid.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the date is the last day of the month</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to check</doc> + <type name="Date" c:type="const GDate*"/> + </instance-parameter> + </parameters> + </method> + <method name="order" c:identifier="g_date_order"> + <doc xml:space="preserve">Checks if @date1 is less than or equal to @date2, +and swap the values if this is not the case.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date1" transfer-ownership="none"> + <doc xml:space="preserve">the first date</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="date2" transfer-ownership="none"> + <doc xml:space="preserve">the second date</doc> + <type name="Date" c:type="GDate*"/> + </parameter> + </parameters> + </method> + <method name="set_day" c:identifier="g_date_set_day"> + <doc xml:space="preserve">Sets the day of the month for a #GDate. If the resulting +day-month-year triplet is invalid, the date will be invalid.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="day" transfer-ownership="none"> + <doc xml:space="preserve">day to set</doc> + <type name="DateDay" c:type="GDateDay"/> + </parameter> + </parameters> + </method> + <method name="set_dmy" c:identifier="g_date_set_dmy"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="day" transfer-ownership="none"> + <doc xml:space="preserve">day</doc> + <type name="DateDay" c:type="GDateDay"/> + </parameter> + <parameter name="month" transfer-ownership="none"> + <doc xml:space="preserve">month</doc> + <type name="DateMonth" c:type="GDateMonth"/> + </parameter> + <parameter name="y" transfer-ownership="none"> + <doc xml:space="preserve">year</doc> + <type name="DateYear" c:type="GDateYear"/> + </parameter> + </parameters> + </method> + <method name="set_julian" c:identifier="g_date_set_julian"> + <doc xml:space="preserve">Sets the value of a #GDate from a Julian day number.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="julian_date" transfer-ownership="none"> + <doc xml:space="preserve">Julian day number (days since January 1, Year 1)</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + </parameters> + </method> + <method name="set_month" c:identifier="g_date_set_month"> + <doc xml:space="preserve">Sets the month of the year for a #GDate. If the resulting +day-month-year triplet is invalid, the date will be invalid.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="month" transfer-ownership="none"> + <doc xml:space="preserve">month to set</doc> + <type name="DateMonth" c:type="GDateMonth"/> + </parameter> + </parameters> + </method> + <method name="set_parse" c:identifier="g_date_set_parse"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to fill in</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">string to parse</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_time" c:identifier="g_date_set_time" deprecated="1" deprecated-version="2.10"> + <doc xml:space="preserve">Sets the value of a date from a #GTime value. +The time to date conversion is done using the user's current timezone.</doc> + <doc-deprecated xml:space="preserve">Use g_date_set_time_t() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate.</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="time_" transfer-ownership="none"> + <doc xml:space="preserve">#GTime value to set.</doc> + <type name="Time" c:type="GTime"/> + </parameter> + </parameters> + </method> + <method name="set_time_t" c:identifier="g_date_set_time_t" version="2.10"> + <doc xml:space="preserve">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); +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="timet" transfer-ownership="none"> + <doc xml:space="preserve">time_t value to set</doc> + <type name="glong" c:type="time_t"/> + </parameter> + </parameters> + </method> + <method name="set_time_val" c:identifier="g_date_set_time_val" version="2.10" deprecated="1" deprecated-version="2.62"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use g_date_set_time_t() + instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="timeval" transfer-ownership="none"> + <doc xml:space="preserve">#GTimeVal value to set</doc> + <type name="TimeVal" c:type="GTimeVal*"/> + </parameter> + </parameters> + </method> + <method name="set_year" c:identifier="g_date_set_year"> + <doc xml:space="preserve">Sets the year for a #GDate. If the resulting day-month-year +triplet is invalid, the date will be invalid.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">year to set</doc> + <type name="DateYear" c:type="GDateYear"/> + </parameter> + </parameters> + </method> + <method name="subtract_days" c:identifier="g_date_subtract_days"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to decrement</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="n_days" transfer-ownership="none"> + <doc xml:space="preserve">number of days to move</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="subtract_months" c:identifier="g_date_subtract_months"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to decrement</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="n_months" transfer-ownership="none"> + <doc xml:space="preserve">number of months to move</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="subtract_years" c:identifier="g_date_subtract_years"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to decrement</doc> + <type name="Date" c:type="GDate*"/> + </instance-parameter> + <parameter name="n_years" transfer-ownership="none"> + <doc xml:space="preserve">number of years to move</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="to_struct_tm" c:identifier="g_date_to_struct_tm"> + <doc xml:space="preserve">Fills in the date-related bits of a struct tm using the @date value. +Initializes the non-date parts with something safe but meaningless.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to set the struct tm from</doc> + <type name="Date" c:type="const GDate*"/> + </instance-parameter> + <parameter name="tm" transfer-ownership="none"> + <doc xml:space="preserve">struct tm to fill</doc> + <type name="gpointer" c:type="tm*"/> + </parameter> + </parameters> + </method> + <method name="valid" c:identifier="g_date_valid"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Whether the date is valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">a #GDate to check</doc> + <type name="Date" c:type="const GDate*"/> + </instance-parameter> + </parameters> + </method> + <function name="get_days_in_month" c:identifier="g_date_get_days_in_month"> + <doc xml:space="preserve">Returns the number of days in a month, taking leap +years into account.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">number of days in @month during the @year</doc> + <type name="guint8" c:type="guint8"/> + </return-value> + <parameters> + <parameter name="month" transfer-ownership="none"> + <doc xml:space="preserve">month</doc> + <type name="DateMonth" c:type="GDateMonth"/> + </parameter> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">year</doc> + <type name="DateYear" c:type="GDateYear"/> + </parameter> + </parameters> + </function> + <function name="get_monday_weeks_in_year" c:identifier="g_date_get_monday_weeks_in_year"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">number of Mondays in the year</doc> + <type name="guint8" c:type="guint8"/> + </return-value> + <parameters> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">a year</doc> + <type name="DateYear" c:type="GDateYear"/> + </parameter> + </parameters> + </function> + <function name="get_sunday_weeks_in_year" c:identifier="g_date_get_sunday_weeks_in_year"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of weeks in @year</doc> + <type name="guint8" c:type="guint8"/> + </return-value> + <parameters> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">year to count weeks in</doc> + <type name="DateYear" c:type="GDateYear"/> + </parameter> + </parameters> + </function> + <function name="is_leap_year" c:identifier="g_date_is_leap_year"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the year is a leap year</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">year to check</doc> + <type name="DateYear" c:type="GDateYear"/> + </parameter> + </parameters> + </function> + <function name="strftime" c:identifier="g_date_strftime"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">number of characters written to the buffer, or 0 the buffer was too small</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="s" transfer-ownership="none"> + <doc xml:space="preserve">destination buffer</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="slen" transfer-ownership="none"> + <doc xml:space="preserve">buffer size</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">valid #GDate</doc> + <type name="Date" c:type="const GDate*"/> + </parameter> + </parameters> + </function> + <function name="valid_day" c:identifier="g_date_valid_day"> + <doc xml:space="preserve">Returns %TRUE if the day of the month is valid (a day is valid if it's +between 1 and 31 inclusive).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the day is valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="day" transfer-ownership="none"> + <doc xml:space="preserve">day to check</doc> + <type name="DateDay" c:type="GDateDay"/> + </parameter> + </parameters> + </function> + <function name="valid_dmy" c:identifier="g_date_valid_dmy"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the date is a valid one</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="day" transfer-ownership="none"> + <doc xml:space="preserve">day</doc> + <type name="DateDay" c:type="GDateDay"/> + </parameter> + <parameter name="month" transfer-ownership="none"> + <doc xml:space="preserve">month</doc> + <type name="DateMonth" c:type="GDateMonth"/> + </parameter> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">year</doc> + <type name="DateYear" c:type="GDateYear"/> + </parameter> + </parameters> + </function> + <function name="valid_julian" c:identifier="g_date_valid_julian"> + <doc xml:space="preserve">Returns %TRUE if the Julian day is valid. Anything greater than zero +is basically a valid Julian, though there is a 32-bit limit.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the Julian day is valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="julian_date" transfer-ownership="none"> + <doc xml:space="preserve">Julian day to check</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + </parameters> + </function> + <function name="valid_month" c:identifier="g_date_valid_month"> + <doc xml:space="preserve">Returns %TRUE if the month value is valid. The 12 #GDateMonth +enumeration values are the only valid months.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the month is valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="month" transfer-ownership="none"> + <doc xml:space="preserve">month</doc> + <type name="DateMonth" c:type="GDateMonth"/> + </parameter> + </parameters> + </function> + <function name="valid_weekday" c:identifier="g_date_valid_weekday"> + <doc xml:space="preserve">Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration +values are the only valid weekdays.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the weekday is valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="weekday" transfer-ownership="none"> + <doc xml:space="preserve">weekday</doc> + <type name="DateWeekday" c:type="GDateWeekday"/> + </parameter> + </parameters> + </function> + <function name="valid_year" c:identifier="g_date_valid_year"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the year is valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">year</doc> + <type name="DateYear" c:type="GDateYear"/> + </parameter> + </parameters> + </function> + </record> + <enumeration name="DateDMY" c:type="GDateDMY"> + <doc xml:space="preserve">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.</doc> + <member name="day" value="0" c:identifier="G_DATE_DAY"> + <doc xml:space="preserve">a day</doc> + </member> + <member name="month" value="1" c:identifier="G_DATE_MONTH"> + <doc xml:space="preserve">a month</doc> + </member> + <member name="year" value="2" c:identifier="G_DATE_YEAR"> + <doc xml:space="preserve">a year</doc> + </member> + </enumeration> + <enumeration name="DateMonth" c:type="GDateMonth"> + <doc xml:space="preserve">Enumeration representing a month; values are #G_DATE_JANUARY, +#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value.</doc> + <member name="bad_month" value="0" c:identifier="G_DATE_BAD_MONTH"> + <doc xml:space="preserve">invalid value</doc> + </member> + <member name="january" value="1" c:identifier="G_DATE_JANUARY"> + <doc xml:space="preserve">January</doc> + </member> + <member name="february" value="2" c:identifier="G_DATE_FEBRUARY"> + <doc xml:space="preserve">February</doc> + </member> + <member name="march" value="3" c:identifier="G_DATE_MARCH"> + <doc xml:space="preserve">March</doc> + </member> + <member name="april" value="4" c:identifier="G_DATE_APRIL"> + <doc xml:space="preserve">April</doc> + </member> + <member name="may" value="5" c:identifier="G_DATE_MAY"> + <doc xml:space="preserve">May</doc> + </member> + <member name="june" value="6" c:identifier="G_DATE_JUNE"> + <doc xml:space="preserve">June</doc> + </member> + <member name="july" value="7" c:identifier="G_DATE_JULY"> + <doc xml:space="preserve">July</doc> + </member> + <member name="august" value="8" c:identifier="G_DATE_AUGUST"> + <doc xml:space="preserve">August</doc> + </member> + <member name="september" value="9" c:identifier="G_DATE_SEPTEMBER"> + <doc xml:space="preserve">September</doc> + </member> + <member name="october" value="10" c:identifier="G_DATE_OCTOBER"> + <doc xml:space="preserve">October</doc> + </member> + <member name="november" value="11" c:identifier="G_DATE_NOVEMBER"> + <doc xml:space="preserve">November</doc> + </member> + <member name="december" value="12" c:identifier="G_DATE_DECEMBER"> + <doc xml:space="preserve">December</doc> + </member> + </enumeration> + <record name="DateTime" c:type="GDateTime" version="2.26" glib:type-name="GDateTime" glib:get-type="g_date_time_get_type" c:symbol-prefix="date_time"> + <doc xml:space="preserve">`GDateTime` is an opaque structure whose members +cannot be accessed directly.</doc> + <constructor name="new" c:identifier="g_date_time_new" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new #GDateTime, or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <parameter name="tz" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeZone</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </parameter> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">the year component of the date</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="month" transfer-ownership="none"> + <doc xml:space="preserve">the month component of the date</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="day" transfer-ownership="none"> + <doc xml:space="preserve">the day component of the date</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="hour" transfer-ownership="none"> + <doc xml:space="preserve">the hour component of the date</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="minute" transfer-ownership="none"> + <doc xml:space="preserve">the minute component of the date</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="seconds" transfer-ownership="none"> + <doc xml:space="preserve">the number of seconds past the minute</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_iso8601" c:identifier="g_date_time_new_from_iso8601" version="2.56"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new #GDateTime, or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <parameter name="text" transfer-ownership="none"> + <doc xml:space="preserve">an ISO 8601 formatted time string.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="default_tz" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GTimeZone to use if the text doesn't contain a + timezone, or %NULL.</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_timeval_local" c:identifier="g_date_time_new_from_timeval_local" version="2.26" deprecated="1" deprecated-version="2.62"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use + g_date_time_new_from_unix_local() instead.</doc-deprecated> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new #GDateTime, or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <parameter name="tv" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeVal</doc> + <type name="TimeVal" c:type="const GTimeVal*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_timeval_utc" c:identifier="g_date_time_new_from_timeval_utc" version="2.26" deprecated="1" deprecated-version="2.62"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use + g_date_time_new_from_unix_utc() instead.</doc-deprecated> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new #GDateTime, or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <parameter name="tv" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeVal</doc> + <type name="TimeVal" c:type="const GTimeVal*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_unix_local" c:identifier="g_date_time_new_from_unix_local" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new #GDateTime, or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <parameter name="t" transfer-ownership="none"> + <doc xml:space="preserve">the Unix time</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_unix_utc" c:identifier="g_date_time_new_from_unix_utc" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new #GDateTime, or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <parameter name="t" transfer-ownership="none"> + <doc xml:space="preserve">the Unix time</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_local" c:identifier="g_date_time_new_local" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GDateTime, or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">the year component of the date</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="month" transfer-ownership="none"> + <doc xml:space="preserve">the month component of the date</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="day" transfer-ownership="none"> + <doc xml:space="preserve">the day component of the date</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="hour" transfer-ownership="none"> + <doc xml:space="preserve">the hour component of the date</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="minute" transfer-ownership="none"> + <doc xml:space="preserve">the minute component of the date</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="seconds" transfer-ownership="none"> + <doc xml:space="preserve">the number of seconds past the minute</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_now" c:identifier="g_date_time_new_now" version="2.26"> + <doc xml:space="preserve">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 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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new #GDateTime, or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <parameter name="tz" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeZone</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_now_local" c:identifier="g_date_time_new_now_local" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new #GDateTime, or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + </constructor> + <constructor name="new_now_utc" c:identifier="g_date_time_new_now_utc" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new #GDateTime, or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + </constructor> + <constructor name="new_utc" c:identifier="g_date_time_new_utc" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GDateTime, or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">the year component of the date</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="month" transfer-ownership="none"> + <doc xml:space="preserve">the month component of the date</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="day" transfer-ownership="none"> + <doc xml:space="preserve">the day component of the date</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="hour" transfer-ownership="none"> + <doc xml:space="preserve">the hour component of the date</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="minute" transfer-ownership="none"> + <doc xml:space="preserve">the minute component of the date</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="seconds" transfer-ownership="none"> + <doc xml:space="preserve">the number of seconds past the minute</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + </parameters> + </constructor> + <method name="add" c:identifier="g_date_time_add" version="2.26"> + <doc xml:space="preserve">Creates a copy of @datetime and adds the specified timespan to the copy.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + <parameter name="timespan" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeSpan</doc> + <type name="TimeSpan" c:type="GTimeSpan"/> + </parameter> + </parameters> + </method> + <method name="add_days" c:identifier="g_date_time_add_days" version="2.26"> + <doc xml:space="preserve">Creates a copy of @datetime and adds the specified number of days to the +copy. Add negative values to subtract days.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + <parameter name="days" transfer-ownership="none"> + <doc xml:space="preserve">the number of days</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="add_full" c:identifier="g_date_time_add_full" version="2.26"> + <doc xml:space="preserve">Creates a new #GDateTime adding the specified values to the current date and +time in @datetime. Add negative values to subtract.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + <parameter name="years" transfer-ownership="none"> + <doc xml:space="preserve">the number of years to add</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="months" transfer-ownership="none"> + <doc xml:space="preserve">the number of months to add</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="days" transfer-ownership="none"> + <doc xml:space="preserve">the number of days to add</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="hours" transfer-ownership="none"> + <doc xml:space="preserve">the number of hours to add</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="minutes" transfer-ownership="none"> + <doc xml:space="preserve">the number of minutes to add</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="seconds" transfer-ownership="none"> + <doc xml:space="preserve">the number of seconds to add</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + </parameters> + </method> + <method name="add_hours" c:identifier="g_date_time_add_hours" version="2.26"> + <doc xml:space="preserve">Creates a copy of @datetime and adds the specified number of hours. +Add negative values to subtract hours.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + <parameter name="hours" transfer-ownership="none"> + <doc xml:space="preserve">the number of hours to add</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="add_minutes" c:identifier="g_date_time_add_minutes" version="2.26"> + <doc xml:space="preserve">Creates a copy of @datetime adding the specified number of minutes. +Add negative values to subtract minutes.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + <parameter name="minutes" transfer-ownership="none"> + <doc xml:space="preserve">the number of minutes to add</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="add_months" c:identifier="g_date_time_add_months" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + <parameter name="months" transfer-ownership="none"> + <doc xml:space="preserve">the number of months</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="add_seconds" c:identifier="g_date_time_add_seconds" version="2.26"> + <doc xml:space="preserve">Creates a copy of @datetime and adds the specified number of seconds. +Add negative values to subtract seconds.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + <parameter name="seconds" transfer-ownership="none"> + <doc xml:space="preserve">the number of seconds to add</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + </parameters> + </method> + <method name="add_weeks" c:identifier="g_date_time_add_weeks" version="2.26"> + <doc xml:space="preserve">Creates a copy of @datetime and adds the specified number of weeks to the +copy. Add negative values to subtract weeks.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + <parameter name="weeks" transfer-ownership="none"> + <doc xml:space="preserve">the number of weeks</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="add_years" c:identifier="g_date_time_add_years" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + <parameter name="years" transfer-ownership="none"> + <doc xml:space="preserve">the number of years</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="compare" c:identifier="g_date_time_compare" version="2.26"> + <doc xml:space="preserve">A comparison function for #GDateTimes that is suitable +as a #GCompareFunc. Both #GDateTimes must be non-%NULL.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">-1, 0 or 1 if @dt1 is less than, equal to or greater + than @dt2.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="dt1" transfer-ownership="none"> + <doc xml:space="preserve">first #GDateTime to compare</doc> + <type name="DateTime" c:type="gconstpointer"/> + </instance-parameter> + <parameter name="dt2" transfer-ownership="none"> + <doc xml:space="preserve">second #GDateTime to compare</doc> + <type name="DateTime" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="difference" c:identifier="g_date_time_difference" version="2.26"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the difference between the two #GDateTime, as a time + span expressed in microseconds.</doc> + <type name="TimeSpan" c:type="GTimeSpan"/> + </return-value> + <parameters> + <instance-parameter name="end" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + <parameter name="begin" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </parameter> + </parameters> + </method> + <method name="equal" c:identifier="g_date_time_equal" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @dt1 and @dt2 are equal</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="dt1" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="gconstpointer"/> + </instance-parameter> + <parameter name="dt2" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="format" c:identifier="g_date_time_format" version="2.26"> + <doc xml:space="preserve">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. The Python extension \%f is also supported. + +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) +- \%f: the microsecond as a decimal number (range 000000 to 999999) +- \%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". Use of this format specifier is discouraged, as + many locales have no concept of AM/PM formatting. Use \%c or \%X instead. +- \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for + the current locale. Use of this format specifier is discouraged, as + many locales have no concept of AM/PM formatting. Use \%c or \%X instead. +- \%r: the time in a.m. or p.m. notation. Use of this format specifier is + discouraged, as many locales have no concept of AM/PM formatting. Use \%c + or \%X instead. +- \%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</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">A #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a valid UTF-8 string, containing the format for the + #GDateTime</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="format_iso8601" c:identifier="g_date_time_format_iso8601" version="2.62"> + <doc xml:space="preserve">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. + +Since GLib 2.66, this will output to sub-second precision if needed.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">A #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_day_of_month" c:identifier="g_date_time_get_day_of_month" version="2.26"> + <doc xml:space="preserve">Retrieves the day of the month represented by @datetime in the gregorian +calendar.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the day of the month</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_day_of_week" c:identifier="g_date_time_get_day_of_week" version="2.26"> + <doc xml:space="preserve">Retrieves the ISO 8601 day of the week on which @datetime falls (1 is +Monday, 2 is Tuesday... 7 is Sunday).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the day of the week</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_day_of_year" c:identifier="g_date_time_get_day_of_year" version="2.26"> + <doc xml:space="preserve">Retrieves the day of the year represented by @datetime in the Gregorian +calendar.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the day of the year</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_hour" c:identifier="g_date_time_get_hour" version="2.26"> + <doc xml:space="preserve">Retrieves the hour of the day represented by @datetime</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the hour of the day</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_microsecond" c:identifier="g_date_time_get_microsecond" version="2.26"> + <doc xml:space="preserve">Retrieves the microsecond of the date represented by @datetime</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the microsecond of the second</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_minute" c:identifier="g_date_time_get_minute" version="2.26"> + <doc xml:space="preserve">Retrieves the minute of the hour represented by @datetime</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the minute of the hour</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_month" c:identifier="g_date_time_get_month" version="2.26"> + <doc xml:space="preserve">Retrieves the month of the year represented by @datetime in the Gregorian +calendar.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the month represented by @datetime</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_second" c:identifier="g_date_time_get_second" version="2.26"> + <doc xml:space="preserve">Retrieves the second of the minute represented by @datetime</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the second represented by @datetime</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_seconds" c:identifier="g_date_time_get_seconds" version="2.26"> + <doc xml:space="preserve">Retrieves the number of seconds since the start of the last minute, +including the fractional part.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of seconds</doc> + <type name="gdouble" c:type="gdouble"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_timezone" c:identifier="g_date_time_get_timezone" version="2.58"> + <doc xml:space="preserve">Get the time zone for this @datetime.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the time zone</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_timezone_abbreviation" c:identifier="g_date_time_get_timezone_abbreviation" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the time zone abbreviation. The returned + string is owned by the #GDateTime and it should not be + modified or freed</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_utc_offset" c:identifier="g_date_time_get_utc_offset" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of microseconds that should be added to UTC to + get the local time</doc> + <type name="TimeSpan" c:type="GTimeSpan"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_week_numbering_year" c:identifier="g_date_time_get_week_numbering_year" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ISO 8601 week-numbering year for @datetime</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_week_of_year" c:identifier="g_date_time_get_week_of_year" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ISO 8601 week number for @datetime.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_year" c:identifier="g_date_time_get_year" version="2.26"> + <doc xml:space="preserve">Retrieves the year represented by @datetime in the Gregorian calendar.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the year represented by @datetime</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">A #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_ymd" c:identifier="g_date_time_get_ymd" version="2.26"> + <doc xml:space="preserve">Retrieves the Gregorian day, month, and year of a given #GDateTime.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime.</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + <parameter name="year" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the return location for the gregorian year, or %NULL.</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="month" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the return location for the month of the year, or %NULL.</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="day" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the return location for the day of the month, or %NULL.</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </method> + <method name="hash" c:identifier="g_date_time_hash" version="2.26"> + <doc xml:space="preserve">Hashes @datetime into a #guint, suitable for use within #GHashTable.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #guint containing the hash</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="gconstpointer"/> + </instance-parameter> + </parameters> + </method> + <method name="is_daylight_savings" c:identifier="g_date_time_is_daylight_savings" version="2.26"> + <doc xml:space="preserve">Determines if daylight savings time is in effect at the time and in +the time zone of @datetime.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if daylight savings time is in effect</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_date_time_ref" version="2.26"> + <doc xml:space="preserve">Atomically increments the reference count of @datetime by one.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the #GDateTime with the reference count increased</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="to_local" c:identifier="g_date_time_to_local" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="to_timeval" c:identifier="g_date_time_to_timeval" version="2.26" deprecated="1" deprecated-version="2.62"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use + g_date_time_to_unix() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful, else %FALSE</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + <parameter name="tv" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeVal to modify</doc> + <type name="TimeVal" c:type="GTimeVal*"/> + </parameter> + </parameters> + </method> + <method name="to_timezone" c:identifier="g_date_time_to_timezone" version="2.26"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + <parameter name="tz" transfer-ownership="none"> + <doc xml:space="preserve">the new #GTimeZone</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </parameter> + </parameters> + </method> + <method name="to_unix" c:identifier="g_date_time_to_unix" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the Unix time corresponding to @datetime</doc> + <type name="gint64" c:type="gint64"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="to_utc" c:identifier="g_date_time_to_utc" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL</doc> + <type name="DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_date_time_unref" version="2.26"> + <doc xml:space="preserve">Atomically decrements the reference count of @datetime by one. + +When the reference count reaches zero, the resources allocated by +@datetime are freed</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="datetime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime</doc> + <type name="DateTime" c:type="GDateTime*"/> + </instance-parameter> + </parameters> + </method> + </record> + <enumeration name="DateWeekday" c:type="GDateWeekday"> + <doc xml:space="preserve">Enumeration representing a day of the week; #G_DATE_MONDAY, +#G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday.</doc> + <member name="bad_weekday" value="0" c:identifier="G_DATE_BAD_WEEKDAY"> + <doc xml:space="preserve">invalid value</doc> + </member> + <member name="monday" value="1" c:identifier="G_DATE_MONDAY"> + <doc xml:space="preserve">Monday</doc> + </member> + <member name="tuesday" value="2" c:identifier="G_DATE_TUESDAY"> + <doc xml:space="preserve">Tuesday</doc> + </member> + <member name="wednesday" value="3" c:identifier="G_DATE_WEDNESDAY"> + <doc xml:space="preserve">Wednesday</doc> + </member> + <member name="thursday" value="4" c:identifier="G_DATE_THURSDAY"> + <doc xml:space="preserve">Thursday</doc> + </member> + <member name="friday" value="5" c:identifier="G_DATE_FRIDAY"> + <doc xml:space="preserve">Friday</doc> + </member> + <member name="saturday" value="6" c:identifier="G_DATE_SATURDAY"> + <doc xml:space="preserve">Saturday</doc> + </member> + <member name="sunday" value="7" c:identifier="G_DATE_SUNDAY"> + <doc xml:space="preserve">Sunday</doc> + </member> + </enumeration> + <record name="DebugKey" c:type="GDebugKey"> + <doc xml:space="preserve">Associates a string with a bit flag. +Used in g_parse_debug_string().</doc> + <field name="key" writable="1"> + <doc xml:space="preserve">the string</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="value" writable="1"> + <doc xml:space="preserve">the flag</doc> + <type name="guint" c:type="guint"/> + </field> + </record> + <callback name="DestroyNotify" c:type="GDestroyNotify"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data element.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="Dir" c:type="GDir" disguised="1"> + <doc xml:space="preserve">An opaque structure representing an opened directory.</doc> + <method name="close" c:identifier="g_dir_close"> + <doc xml:space="preserve">Closes the directory and deallocates all related resources.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="dir" transfer-ownership="none"> + <doc xml:space="preserve">a #GDir* created by g_dir_open()</doc> + <type name="Dir" c:type="GDir*"/> + </instance-parameter> + </parameters> + </method> + <method name="read_name" c:identifier="g_dir_read_name"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="dir" transfer-ownership="none"> + <doc xml:space="preserve">a #GDir* created by g_dir_open()</doc> + <type name="Dir" c:type="GDir*"/> + </instance-parameter> + </parameters> + </method> + <method name="rewind" c:identifier="g_dir_rewind"> + <doc xml:space="preserve">Resets the given directory. The next call to g_dir_read_name() +will return the first entry again.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="dir" transfer-ownership="none"> + <doc xml:space="preserve">a #GDir* created by g_dir_open()</doc> + <type name="Dir" c:type="GDir*"/> + </instance-parameter> + </parameters> + </method> + <function name="make_tmp" c:identifier="g_dir_make_tmp" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="tmpl" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Template for directory name, + as in g_mkdtemp(), basename only, or %NULL for a default template</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="open" c:identifier="g_dir_open" introspectable="0" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">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.</doc> + <type name="Dir" c:type="GDir*"/> + </return-value> + <parameters> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the path to the directory you are interested in. On Unix + in the on-disk encoding. On Windows in UTF-8</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Currently must be set to 0. Reserved for future use.</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + </record> + <union name="DoubleIEEE754" c:type="GDoubleIEEE754"> + <doc xml:space="preserve">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.</doc> + <field name="v_double" writable="1"> + <doc xml:space="preserve">the double value</doc> + <type name="gdouble" c:type="gdouble"/> + </field> + <record name="mpn" c:type="mpn"> + <field name="mantissa_low" writable="1" bits="32"> + <type name="guint" c:type="guint"/> + </field> + <field name="mantissa_high" writable="1" bits="20"> + <type name="guint" c:type="guint"/> + </field> + <field name="biased_exponent" writable="1" bits="11"> + <type name="guint" c:type="guint"/> + </field> + <field name="sign" writable="1" bits="1"> + <type name="guint" c:type="guint"/> + </field> + </record> + </union> + <callback name="DuplicateFunc" c:type="GDuplicateFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a duplicate of data</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to duplicate</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="1"> + <doc xml:space="preserve">user data that was specified in + g_datalist_id_dup_data()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <constant name="E" value="2.718282" c:type="G_E"> + <doc xml:space="preserve">The base of natural logarithms.</doc> + <type name="gdouble" c:type="gdouble"/> + </constant> + <function-macro name="ENCODE_VERSION" c:identifier="G_ENCODE_VERSION" introspectable="0"> + <parameters> + <parameter name="major"> + </parameter> + <parameter name="minor"> + </parameter> + </parameters> + </function-macro> + <callback name="EqualFunc" c:type="GEqualFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @a = @b; %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="a" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a value</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="b" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a value to compare with</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </callback> + <record name="Error" c:type="GError" glib:type-name="GError" glib:get-type="g_error_get_type" c:symbol-prefix="error"> + <doc xml:space="preserve">The `GError` structure contains information about +an error that has occurred.</doc> + <field name="domain" writable="1"> + <doc xml:space="preserve">error domain, e.g. #G_FILE_ERROR</doc> + <type name="Quark" c:type="GQuark"/> + </field> + <field name="code" writable="1"> + <doc xml:space="preserve">error code, e.g. %G_FILE_ERROR_NOENT</doc> + <type name="gint" c:type="gint"/> + </field> + <field name="message" writable="1"> + <doc xml:space="preserve">human-readable informative error message</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <constructor name="new" c:identifier="g_error_new" introspectable="0"> + <doc xml:space="preserve">Creates a new #GError with the given @domain and @code, +and a message formatted with @format.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GError</doc> + <type name="Error" c:type="GError*"/> + </return-value> + <parameters> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">error domain</doc> + <type name="Quark" c:type="GQuark"/> + </parameter> + <parameter name="code" transfer-ownership="none"> + <doc xml:space="preserve">error code</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">printf()-style format for error message</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">parameters for message format</doc> + <varargs/> + </parameter> + </parameters> + </constructor> + <constructor name="new_literal" c:identifier="g_error_new_literal"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GError</doc> + <type name="Error" c:type="GError*"/> + </return-value> + <parameters> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">error domain</doc> + <type name="Quark" c:type="GQuark"/> + </parameter> + <parameter name="code" transfer-ownership="none"> + <doc xml:space="preserve">error code</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">error message</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_valist" c:identifier="g_error_new_valist" version="2.22" introspectable="0"> + <doc xml:space="preserve">Creates a new #GError with the given @domain and @code, +and a message formatted with @format.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GError</doc> + <type name="Error" c:type="GError*"/> + </return-value> + <parameters> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">error domain</doc> + <type name="Quark" c:type="GQuark"/> + </parameter> + <parameter name="code" transfer-ownership="none"> + <doc xml:space="preserve">error code</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">printf()-style format for error message</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">#va_list of parameters for the message format</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </constructor> + <method name="copy" c:identifier="g_error_copy"> + <doc xml:space="preserve">Makes a copy of @error.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GError</doc> + <type name="Error" c:type="GError*"/> + </return-value> + <parameters> + <instance-parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">a #GError</doc> + <type name="Error" c:type="const GError*"/> + </instance-parameter> + </parameters> + </method> + <method name="free" c:identifier="g_error_free"> + <doc xml:space="preserve">Frees a #GError and associated resources.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">a #GError</doc> + <type name="Error" c:type="GError*"/> + </instance-parameter> + </parameters> + </method> + <method name="matches" c:identifier="g_error_matches"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether @error has @domain and @code</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="error" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GError</doc> + <type name="Error" c:type="const GError*"/> + </instance-parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">an error domain</doc> + <type name="Quark" c:type="GQuark"/> + </parameter> + <parameter name="code" transfer-ownership="none"> + <doc xml:space="preserve">an error code</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + </record> + <enumeration name="ErrorType" c:type="GErrorType"> + <doc xml:space="preserve">The possible errors, used in the @v_error field +of #GTokenValue, when the token is a %G_TOKEN_ERROR.</doc> + <member name="unknown" value="0" c:identifier="G_ERR_UNKNOWN"> + <doc xml:space="preserve">unknown error</doc> + </member> + <member name="unexp_eof" value="1" c:identifier="G_ERR_UNEXP_EOF"> + <doc xml:space="preserve">unexpected end of file</doc> + </member> + <member name="unexp_eof_in_string" value="2" c:identifier="G_ERR_UNEXP_EOF_IN_STRING"> + <doc xml:space="preserve">unterminated string constant</doc> + </member> + <member name="unexp_eof_in_comment" value="3" c:identifier="G_ERR_UNEXP_EOF_IN_COMMENT"> + <doc xml:space="preserve">unterminated comment</doc> + </member> + <member name="non_digit_in_const" value="4" c:identifier="G_ERR_NON_DIGIT_IN_CONST"> + <doc xml:space="preserve">non-digit character in a number</doc> + </member> + <member name="digit_radix" value="5" c:identifier="G_ERR_DIGIT_RADIX"> + <doc xml:space="preserve">digit beyond radix in a number</doc> + </member> + <member name="float_radix" value="6" c:identifier="G_ERR_FLOAT_RADIX"> + <doc xml:space="preserve">non-decimal floating point number</doc> + </member> + <member name="float_malformed" value="7" c:identifier="G_ERR_FLOAT_MALFORMED"> + <doc xml:space="preserve">malformed floating point number</doc> + </member> + </enumeration> + <enumeration name="FileError" c:type="GFileError" glib:error-domain="g-file-error-quark"> + <doc xml:space="preserve">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.</doc> + <member name="exist" value="0" c:identifier="G_FILE_ERROR_EXIST"> + <doc xml:space="preserve">Operation not permitted; only the owner of + the file (or other resource) or processes with special privileges + can perform the operation.</doc> + </member> + <member name="isdir" value="1" c:identifier="G_FILE_ERROR_ISDIR"> + <doc xml:space="preserve">File is a directory; you cannot open a directory + for writing, or create or remove hard links to it.</doc> + </member> + <member name="acces" value="2" c:identifier="G_FILE_ERROR_ACCES"> + <doc xml:space="preserve">Permission denied; the file permissions do not + allow the attempted operation.</doc> + </member> + <member name="nametoolong" value="3" c:identifier="G_FILE_ERROR_NAMETOOLONG"> + <doc xml:space="preserve">Filename too long.</doc> + </member> + <member name="noent" value="4" c:identifier="G_FILE_ERROR_NOENT"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="notdir" value="5" c:identifier="G_FILE_ERROR_NOTDIR"> + <doc xml:space="preserve">A file that isn't a directory was specified when + a directory is required.</doc> + </member> + <member name="nxio" value="6" c:identifier="G_FILE_ERROR_NXIO"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="nodev" value="7" c:identifier="G_FILE_ERROR_NODEV"> + <doc xml:space="preserve">The underlying file system of the specified file + does not support memory mapping.</doc> + </member> + <member name="rofs" value="8" c:identifier="G_FILE_ERROR_ROFS"> + <doc xml:space="preserve">The directory containing the new link can't be + modified because it's on a read-only file system.</doc> + </member> + <member name="txtbsy" value="9" c:identifier="G_FILE_ERROR_TXTBSY"> + <doc xml:space="preserve">Text file busy.</doc> + </member> + <member name="fault" value="10" c:identifier="G_FILE_ERROR_FAULT"> + <doc xml:space="preserve">You passed in a pointer to bad memory. + (GLib won't reliably return this, don't pass in pointers to bad + memory.)</doc> + </member> + <member name="loop" value="11" c:identifier="G_FILE_ERROR_LOOP"> + <doc xml:space="preserve">Too many levels of symbolic links were encountered + in looking up a file name. This often indicates a cycle of symbolic + links.</doc> + </member> + <member name="nospc" value="12" c:identifier="G_FILE_ERROR_NOSPC"> + <doc xml:space="preserve">No space left on device; write operation on a + file failed because the disk is full.</doc> + </member> + <member name="nomem" value="13" c:identifier="G_FILE_ERROR_NOMEM"> + <doc xml:space="preserve">No memory available. The system cannot allocate + more virtual memory because its capacity is full.</doc> + </member> + <member name="mfile" value="14" c:identifier="G_FILE_ERROR_MFILE"> + <doc xml:space="preserve">The current process has too many files open and + can't open any more. Duplicate descriptors do count toward this + limit.</doc> + </member> + <member name="nfile" value="15" c:identifier="G_FILE_ERROR_NFILE"> + <doc xml:space="preserve">There are too many distinct file openings in the + entire system.</doc> + </member> + <member name="badf" value="16" c:identifier="G_FILE_ERROR_BADF"> + <doc xml:space="preserve">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).</doc> + </member> + <member name="inval" value="17" c:identifier="G_FILE_ERROR_INVAL"> + <doc xml:space="preserve">Invalid argument. This is used to indicate + various kinds of problems with passing the wrong argument to a + library function.</doc> + </member> + <member name="pipe" value="18" c:identifier="G_FILE_ERROR_PIPE"> + <doc xml:space="preserve">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'.</doc> + </member> + <member name="again" value="19" c:identifier="G_FILE_ERROR_AGAIN"> + <doc xml:space="preserve">Resource temporarily unavailable; the call might + work if you try again later.</doc> + </member> + <member name="intr" value="20" c:identifier="G_FILE_ERROR_INTR"> + <doc xml:space="preserve">Interrupted function call; an asynchronous signal + occurred and prevented completion of the call. When this + happens, you should try the call again.</doc> + </member> + <member name="io" value="21" c:identifier="G_FILE_ERROR_IO"> + <doc xml:space="preserve">Input/output error; usually used for physical read + or write errors. i.e. the disk or other physical device hardware + is returning errors.</doc> + </member> + <member name="perm" value="22" c:identifier="G_FILE_ERROR_PERM"> + <doc xml:space="preserve">Operation not permitted; only the owner of the + file (or other resource) or processes with special privileges can + perform the operation.</doc> + </member> + <member name="nosys" value="23" c:identifier="G_FILE_ERROR_NOSYS"> + <doc xml:space="preserve">Function not implemented; this indicates that + the system is missing some functionality.</doc> + </member> + <member name="failed" value="24" c:identifier="G_FILE_ERROR_FAILED"> + <doc xml:space="preserve">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.</doc> + </member> + </enumeration> + <bitfield name="FileSetContentsFlags" version="2.66" c:type="GFileSetContentsFlags"> + <doc xml:space="preserve">Flags to pass to g_file_set_contents_full() to affect its safety and +performance.</doc> + <member name="none" value="0" c:identifier="G_FILE_SET_CONTENTS_NONE"> + <doc xml:space="preserve">No guarantees about file consistency or durability. + The most dangerous setting, which is slightly faster than other settings.</doc> + </member> + <member name="consistent" value="1" c:identifier="G_FILE_SET_CONTENTS_CONSISTENT"> + <doc xml:space="preserve">Guarantee file consistency: after a crash, + either the old version of the file or the new version of the file will be + available, but not a mixture. On Unix systems this equates to an `fsync()` + on the file and use of an atomic `rename()` of the new version of the file + over the old.</doc> + </member> + <member name="durable" value="2" c:identifier="G_FILE_SET_CONTENTS_DURABLE"> + <doc xml:space="preserve">Guarantee file durability: after a crash, the + new version of the file will be available. On Unix systems this equates to + an `fsync()` on the file (if %G_FILE_SET_CONTENTS_CONSISTENT is unset), or + the effects of %G_FILE_SET_CONTENTS_CONSISTENT plus an `fsync()` on the + directory containing the file after calling `rename()`.</doc> + </member> + <member name="only_existing" value="4" c:identifier="G_FILE_SET_CONTENTS_ONLY_EXISTING"> + <doc xml:space="preserve">Only apply consistency and durability + guarantees if the file already exists. This may speed up file operations + if the file doesn’t currently exist, but may result in a corrupted version + of the new file if the system crashes while writing it.</doc> + </member> + </bitfield> + <bitfield name="FileTest" c:type="GFileTest"> + <doc xml:space="preserve">A test to perform on a file using g_file_test().</doc> + <member name="is_regular" value="1" c:identifier="G_FILE_TEST_IS_REGULAR"> + <doc xml:space="preserve">%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.</doc> + </member> + <member name="is_symlink" value="2" c:identifier="G_FILE_TEST_IS_SYMLINK"> + <doc xml:space="preserve">%TRUE if the file is a symlink.</doc> + </member> + <member name="is_dir" value="4" c:identifier="G_FILE_TEST_IS_DIR"> + <doc xml:space="preserve">%TRUE if the file is a directory.</doc> + </member> + <member name="is_executable" value="8" c:identifier="G_FILE_TEST_IS_EXECUTABLE"> + <doc xml:space="preserve">%TRUE if the file is executable.</doc> + </member> + <member name="exists" value="16" c:identifier="G_FILE_TEST_EXISTS"> + <doc xml:space="preserve">%TRUE if the file exists. It may or may not + be a regular file.</doc> + </member> + </bitfield> + <union name="FloatIEEE754" c:type="GFloatIEEE754"> + <doc xml:space="preserve">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.</doc> + <field name="v_float" writable="1"> + <doc xml:space="preserve">the double value</doc> + <type name="gfloat" c:type="gfloat"/> + </field> + <record name="mpn" c:type="mpn"> + <field name="mantissa" writable="1" bits="23"> + <type name="guint" c:type="guint"/> + </field> + <field name="biased_exponent" writable="1" bits="8"> + <type name="guint" c:type="guint"/> + </field> + <field name="sign" writable="1" bits="1"> + <type name="guint" c:type="guint"/> + </field> + </record> + </union> + <bitfield name="FormatSizeFlags" c:type="GFormatSizeFlags"> + <doc xml:space="preserve">Flags to modify the format of the string returned by g_format_size_full().</doc> + <member name="default" value="0" c:identifier="G_FORMAT_SIZE_DEFAULT"> + <doc xml:space="preserve">behave the same as g_format_size()</doc> + </member> + <member name="long_format" value="1" c:identifier="G_FORMAT_SIZE_LONG_FORMAT"> + <doc xml:space="preserve">include the exact number of bytes as part + of the returned string. For example, "45.6 kB (45,612 bytes)".</doc> + </member> + <member name="iec_units" value="2" c:identifier="G_FORMAT_SIZE_IEC_UNITS"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="bits" value="4" c:identifier="G_FORMAT_SIZE_BITS"> + <doc xml:space="preserve">set the size as a quantity in bits, rather than + bytes, and return units in bits. For example, ‘Mb’ rather than ‘MB’.</doc> + </member> + </bitfield> + <callback name="FreeFunc" c:type="GFreeFunc"> + <doc xml:space="preserve">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+.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a data pointer</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="Func" c:type="GFunc"> + <doc xml:space="preserve">Specifies the type of functions passed to g_list_foreach() and +g_slist_foreach().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the element's data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="1"> + <doc xml:space="preserve">user data passed to g_list_foreach() or g_slist_foreach()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <constant name="GINT16_FORMAT" value="hi" c:type="G_GINT16_FORMAT"> + <doc xml:space="preserve">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); +]|</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="GINT16_MODIFIER" value="h" c:type="G_GINT16_MODIFIER" version="2.4"> + <doc xml:space="preserve">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); +]|</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="GINT32_FORMAT" value="i" c:type="G_GINT32_FORMAT"> + <doc xml:space="preserve">This is the platform dependent conversion specifier for scanning +and printing values of type #gint32. See also #G_GINT16_FORMAT.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="GINT32_MODIFIER" value="" c:type="G_GINT32_MODIFIER" version="2.4"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="GINT64_CONSTANT" c:identifier="G_GINT64_CONSTANT" introspectable="0"> + <doc xml:space="preserve">This macro is used to insert 64-bit integer literals +into the source code.</doc> + <parameters> + <parameter name="val"> + <doc xml:space="preserve">a literal integer value, e.g. 0x1d636b02300a7aa7</doc> + </parameter> + </parameters> + </function-macro> + <constant name="GINT64_FORMAT" value="li" c:type="G_GINT64_FORMAT"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="GINT64_MODIFIER" value="l" c:type="G_GINT64_MODIFIER" version="2.4"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="GINTPTR_FORMAT" value="li" c:type="G_GINTPTR_FORMAT" version="2.22"> + <doc xml:space="preserve">This is the platform dependent conversion specifier for scanning +and printing values of type #gintptr.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="GINTPTR_MODIFIER" value="l" c:type="G_GINTPTR_MODIFIER" version="2.22"> + <doc xml:space="preserve">The platform dependent length modifier for conversion specifiers +for scanning and printing values of type #gintptr or #guintptr. +It is a string literal.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="GNUC_ALLOC_SIZE" c:identifier="G_GNUC_ALLOC_SIZE" version="2.18" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="x"> + <doc xml:space="preserve">the index of the argument specifying the allocation size</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="GNUC_ALLOC_SIZE2" c:identifier="G_GNUC_ALLOC_SIZE2" version="2.18" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="x"> + <doc xml:space="preserve">the index of the argument specifying one factor of the allocation size</doc> + </parameter> + <parameter name="y"> + <doc xml:space="preserve">the index of the argument specifying the second factor of the allocation size</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="GNUC_CHECK_VERSION" c:identifier="G_GNUC_CHECK_VERSION" version="2.42" introspectable="0"> + <doc xml:space="preserve">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 +]|</doc> + <parameters> + <parameter name="major"> + <doc xml:space="preserve">major version to check against</doc> + </parameter> + <parameter name="minor"> + <doc xml:space="preserve">minor version to check against</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="GNUC_DEPRECATED_FOR" c:identifier="G_GNUC_DEPRECATED_FOR" version="2.26" introspectable="0"> + <doc xml:space="preserve">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.)</doc> + <parameters> + <parameter name="f"> + <doc xml:space="preserve">the intended replacement for the deprecated symbol, + such as the name of a function</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="GNUC_FORMAT" c:identifier="G_GNUC_FORMAT" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <parameters> + <parameter name="arg_idx"> + <doc xml:space="preserve">the index of the argument</doc> + </parameter> + </parameters> + </function-macro> + <constant name="GNUC_FUNCTION" value="" c:type="G_GNUC_FUNCTION" deprecated="1" deprecated-version="2.16"> + <doc xml:space="preserve">Expands to "" on all modern compilers, and to __FUNCTION__ on gcc +version 2.x. Don't use it.</doc> + <doc-deprecated xml:space="preserve">Use G_STRFUNC() instead</doc-deprecated> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="GNUC_PRETTY_FUNCTION" value="" c:type="G_GNUC_PRETTY_FUNCTION" deprecated="1" deprecated-version="2.16"> + <doc xml:space="preserve">Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__ +on gcc version 2.x. Don't use it.</doc> + <doc-deprecated xml:space="preserve">Use G_STRFUNC() instead</doc-deprecated> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="GNUC_PRINTF" c:identifier="G_GNUC_PRINTF" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <parameters> + <parameter name="format_idx"> + <doc xml:space="preserve">the index of the argument corresponding to the + format string (the arguments are numbered from 1)</doc> + </parameter> + <parameter name="arg_idx"> + <doc xml:space="preserve">the index of the first of the format arguments, or 0 if + there are no format arguments</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="GNUC_SCANF" c:identifier="G_GNUC_SCANF" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="format_idx"> + <doc xml:space="preserve">the index of the argument corresponding to + the format string (the arguments are numbered from 1)</doc> + </parameter> + <parameter name="arg_idx"> + <doc xml:space="preserve">the index of the first of the format arguments, or 0 if + there are no format arguments</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="GNUC_STRFTIME" c:identifier="G_GNUC_STRFTIME" version="2.60" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="format_idx"> + <doc xml:space="preserve">the index of the argument corresponding to + the format string (the arguments are numbered from 1)</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="GOFFSET_CONSTANT" c:identifier="G_GOFFSET_CONSTANT" version="2.20" introspectable="0"> + <doc xml:space="preserve">This macro is used to insert #goffset 64-bit integer literals +into the source code. + +See also #G_GINT64_CONSTANT.</doc> + <parameters> + <parameter name="val"> + <doc xml:space="preserve">a literal integer value, e.g. 0x1d636b02300a7aa7</doc> + </parameter> + </parameters> + </function-macro> + <constant name="GSIZE_FORMAT" value="lu" c:type="G_GSIZE_FORMAT" version="2.6"> + <doc xml:space="preserve">This is the platform dependent conversion specifier for scanning +and printing values of type #gsize. See also #G_GINT16_FORMAT.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="GSIZE_MODIFIER" value="l" c:type="G_GSIZE_MODIFIER" version="2.6"> + <doc xml:space="preserve">The platform dependent length modifier for conversion specifiers +for scanning and printing values of type #gsize. It +is a string literal.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="GSSIZE_FORMAT" value="li" c:type="G_GSSIZE_FORMAT" version="2.6"> + <doc xml:space="preserve">This is the platform dependent conversion specifier for scanning +and printing values of type #gssize. See also #G_GINT16_FORMAT.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="GSSIZE_MODIFIER" value="l" c:type="G_GSSIZE_MODIFIER" version="2.6"> + <doc xml:space="preserve">The platform dependent length modifier for conversion specifiers +for scanning and printing values of type #gssize. It +is a string literal.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="GUINT16_FORMAT" value="hu" c:type="G_GUINT16_FORMAT"> + <doc xml:space="preserve">This is the platform dependent conversion specifier for scanning +and printing values of type #guint16. See also #G_GINT16_FORMAT</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="GUINT32_FORMAT" value="u" c:type="G_GUINT32_FORMAT"> + <doc xml:space="preserve">This is the platform dependent conversion specifier for scanning +and printing values of type #guint32. See also #G_GINT16_FORMAT.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="GUINT64_CONSTANT" c:identifier="G_GUINT64_CONSTANT" version="2.10" introspectable="0"> + <doc xml:space="preserve">This macro is used to insert 64-bit unsigned integer +literals into the source code.</doc> + <parameters> + <parameter name="val"> + <doc xml:space="preserve">a literal integer value, e.g. 0x1d636b02300a7aa7U</doc> + </parameter> + </parameters> + </function-macro> + <constant name="GUINT64_FORMAT" value="lu" c:type="G_GUINT64_FORMAT"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="GUINTPTR_FORMAT" value="lu" c:type="G_GUINTPTR_FORMAT" version="2.22"> + <doc xml:space="preserve">This is the platform dependent conversion specifier +for scanning and printing values of type #guintptr.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="HAVE_GINT64" value="1" c:type="G_HAVE_GINT64"> + <type name="gint" c:type="gint"/> + </constant> + <constant name="HAVE_GNUC_VARARGS" value="1" c:type="G_HAVE_GNUC_VARARGS"> + <type name="gint" c:type="gint"/> + </constant> + <constant name="HAVE_GNUC_VISIBILITY" value="1" c:type="G_HAVE_GNUC_VISIBILITY"> + <doc xml:space="preserve">Defined to 1 if gcc-style visibility handling is supported.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="HAVE_GROWING_STACK" value="0" c:type="G_HAVE_GROWING_STACK"> + <type name="gint" c:type="gint"/> + </constant> + <constant name="HAVE_ISO_VARARGS" value="1" c:type="G_HAVE_ISO_VARARGS"> + <type name="gint" c:type="gint"/> + </constant> + <callback name="HFunc" c:type="GHFunc"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the value corresponding to the key</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">user data passed to g_hash_table_foreach()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <function-macro name="HOOK" c:identifier="G_HOOK" introspectable="0"> + <doc xml:space="preserve">Casts a pointer to a `GHook*`.</doc> + <parameters> + <parameter name="hook"> + <doc xml:space="preserve">a pointer</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="HOOK_ACTIVE" c:identifier="G_HOOK_ACTIVE" introspectable="0"> + <doc xml:space="preserve">Returns %TRUE if the #GHook is active, which is normally the case +until the #GHook is destroyed.</doc> + <parameters> + <parameter name="hook"> + <doc xml:space="preserve">a #GHook</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="HOOK_FLAGS" c:identifier="G_HOOK_FLAGS" introspectable="0"> + <doc xml:space="preserve">Gets the flags of a hook.</doc> + <parameters> + <parameter name="hook"> + <doc xml:space="preserve">a #GHook</doc> + </parameter> + </parameters> + </function-macro> + <constant name="HOOK_FLAG_USER_SHIFT" value="4" c:type="G_HOOK_FLAG_USER_SHIFT"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </constant> + <function-macro name="HOOK_IN_CALL" c:identifier="G_HOOK_IN_CALL" introspectable="0"> + <doc xml:space="preserve">Returns %TRUE if the #GHook function is currently executing.</doc> + <parameters> + <parameter name="hook"> + <doc xml:space="preserve">a #GHook</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="HOOK_IS_UNLINKED" c:identifier="G_HOOK_IS_UNLINKED" introspectable="0"> + <doc xml:space="preserve">Returns %TRUE if the #GHook is not in a #GHookList.</doc> + <parameters> + <parameter name="hook"> + <doc xml:space="preserve">a #GHook</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="HOOK_IS_VALID" c:identifier="G_HOOK_IS_VALID" introspectable="0"> + <doc xml:space="preserve">Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList, +it is active and it has not been destroyed.</doc> + <parameters> + <parameter name="hook"> + <doc xml:space="preserve">a #GHook</doc> + </parameter> + </parameters> + </function-macro> + <callback name="HRFunc" c:type="GHRFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key/value pair should be removed from the + #GHashTable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the value associated with the key</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">user data passed to g_hash_table_remove()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="HashFunc" c:type="GHashFunc"> + <doc xml:space="preserve">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 +vulnerable 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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the hash value corresponding to the key</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </callback> + <record name="HashTable" c:type="GHashTable" glib:type-name="GHashTable" glib:get-type="g_hash_table_get_type" c:symbol-prefix="hash_table"> + <doc xml:space="preserve">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.</doc> + <function name="add" c:identifier="g_hash_table_add" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key did not exist yet</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="key" transfer-ownership="full" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key to insert</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="contains" c:identifier="g_hash_table_contains" version="2.32"> + <doc xml:space="preserve">Checks if @key is in @hash_table.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @key is in @hash_table, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key to check</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="destroy" c:identifier="g_hash_table_destroy"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="find" c:identifier="g_hash_table_find" version="2.4" introspectable="0"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="predicate" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">function to test the key/value pairs for a certain property</doc> + <type name="HRFunc" c:type="GHRFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to the function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="foreach" c:identifier="g_hash_table_foreach" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function to call for each key/value pair</doc> + <type name="HFunc" c:type="GHFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to the function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="foreach_remove" c:identifier="g_hash_table_foreach_remove" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of key/value pairs removed</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function to call for each key/value pair</doc> + <type name="HRFunc" c:type="GHRFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to the function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="foreach_steal" c:identifier="g_hash_table_foreach_steal" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of key/value pairs removed.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function to call for each key/value pair</doc> + <type name="HRFunc" c:type="GHRFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to the function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="get_keys" c:identifier="g_hash_table_get_keys" version="2.14" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="container"> + <doc xml:space="preserve">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.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="get_keys_as_array" c:identifier="g_hash_table_get_keys_as_array" version="2.40" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="container"> + <doc xml:space="preserve">a + %NULL-terminated array containing each key from the table.</doc> + <array length="1" zero-terminated="0" c:type="gpointer*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the length of the returned array</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </function> + <function name="get_values" c:identifier="g_hash_table_get_values" version="2.14" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="container"> + <doc xml:space="preserve">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.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="insert" c:identifier="g_hash_table_insert"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key did not exist yet</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key to insert</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the value to associate with the key</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="lookup" c:identifier="g_hash_table_lookup"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the associated value, or %NULL if the key is not found</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the key to look up</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="lookup_extended" c:identifier="g_hash_table_lookup_extended"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key was found in the #GHashTable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="lookup_key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the key to look up</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="orig_key" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the original key</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + <parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the value associated +with the key</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + </parameters> + </function> + <function name="new" c:identifier="g_hash_table_new" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">a new #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="hash_func" transfer-ownership="none"> + <doc xml:space="preserve">a function to create a hash value from a key</doc> + <type name="HashFunc" c:type="GHashFunc"/> + </parameter> + <parameter name="key_equal_func" transfer-ownership="none"> + <doc xml:space="preserve">a function to check two keys for equality</doc> + <type name="EqualFunc" c:type="GEqualFunc"/> + </parameter> + </parameters> + </function> + <function name="new_full" c:identifier="g_hash_table_new_full" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value> + <doc xml:space="preserve">a new #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="hash_func" transfer-ownership="none"> + <doc xml:space="preserve">a function to create a hash value from a key</doc> + <type name="HashFunc" c:type="GHashFunc"/> + </parameter> + <parameter name="key_equal_func" transfer-ownership="none" scope="notified" destroy="3"> + <doc xml:space="preserve">a function to check two keys for equality</doc> + <type name="EqualFunc" c:type="GEqualFunc"/> + </parameter> + <parameter name="key_destroy_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">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.</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + <parameter name="value_destroy_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">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.</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="ref" c:identifier="g_hash_table_ref" version="2.10" introspectable="0"> + <doc xml:space="preserve">Atomically increments the reference count of @hash_table by one. +This function is MT-safe and may be called from any thread.</doc> + <return-value> + <doc xml:space="preserve">the passed in #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="remove" c:identifier="g_hash_table_remove"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key was found and removed from the #GHashTable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the key to remove</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="remove_all" c:identifier="g_hash_table_remove_all" version="2.12"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="replace" c:identifier="g_hash_table_replace"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key did not exist yet</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key to insert</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the value to associate with the key</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="size" c:identifier="g_hash_table_size"> + <doc xml:space="preserve">Returns the number of elements contained in the #GHashTable.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of key/value pairs in the #GHashTable.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="steal" c:identifier="g_hash_table_steal"> + <doc xml:space="preserve">Removes a key and its associated value from a #GHashTable without +calling the key and value destroy functions.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key was found and removed from the #GHashTable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the key to remove</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="steal_all" c:identifier="g_hash_table_steal_all" version="2.12"> + <doc xml:space="preserve">Removes all keys and their associated values from a #GHashTable +without calling the key and value destroy functions.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="steal_extended" c:identifier="g_hash_table_steal_extended" version="2.58"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key was found in the #GHashTable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="lookup_key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the key to look up</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="stolen_key" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the + original key</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + <parameter name="stolen_value" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">return location + for the value associated with the key</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + </parameters> + </function> + <function name="unref" c:identifier="g_hash_table_unref" version="2.10"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + </record> + <record name="HashTableIter" c:type="GHashTableIter"> + <doc xml:space="preserve">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.</doc> + <field name="dummy1" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="dummy2" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="dummy3" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="dummy4" readable="0" private="1"> + <type name="gint" c:type="int"/> + </field> + <field name="dummy5" readable="0" private="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="dummy6" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <method name="get_hash_table" c:identifier="g_hash_table_iter_get_hash_table" version="2.16" introspectable="0"> + <doc xml:space="preserve">Returns the #GHashTable associated with @iter.</doc> + <return-value> + <doc xml:space="preserve">the #GHashTable associated with @iter.</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">an initialized #GHashTableIter</doc> + <type name="HashTableIter" c:type="GHashTableIter*"/> + </instance-parameter> + </parameters> + </method> + <method name="init" c:identifier="g_hash_table_iter_init" version="2.16"> + <doc xml:space="preserve">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 + } +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">an uninitialized #GHashTableIter</doc> + <type name="HashTableIter" c:type="GHashTableIter*"/> + </instance-parameter> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </method> + <method name="next" c:identifier="g_hash_table_iter_next" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%FALSE if the end of the #GHashTable has been reached.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">an initialized #GHashTableIter</doc> + <type name="HashTableIter" c:type="GHashTableIter*"/> + </instance-parameter> + <parameter name="key" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to store the key</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + <parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to store the value</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + </parameters> + </method> + <method name="remove" c:identifier="g_hash_table_iter_remove" version="2.16"> + <doc xml:space="preserve">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); + } +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">an initialized #GHashTableIter</doc> + <type name="HashTableIter" c:type="GHashTableIter*"/> + </instance-parameter> + </parameters> + </method> + <method name="replace" c:identifier="g_hash_table_iter_replace" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">an initialized #GHashTableIter</doc> + <type name="HashTableIter" c:type="GHashTableIter*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the value to replace with</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="steal" c:identifier="g_hash_table_iter_steal" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">an initialized #GHashTableIter</doc> + <type name="HashTableIter" c:type="GHashTableIter*"/> + </instance-parameter> + </parameters> + </method> + </record> + <record name="Hmac" c:type="GHmac" disguised="1" version="2.30"> + <doc xml:space="preserve">An opaque structure representing a HMAC operation. +To create a new GHmac, use g_hmac_new(). To free +a GHmac, use g_hmac_unref().</doc> + <method name="copy" c:identifier="g_hmac_copy" version="2.30" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the copy of the passed #GHmac. Use g_hmac_unref() + when finished using it.</doc> + <type name="Hmac" c:type="GHmac*"/> + </return-value> + <parameters> + <instance-parameter name="hmac" transfer-ownership="none"> + <doc xml:space="preserve">the #GHmac to copy</doc> + <type name="Hmac" c:type="const GHmac*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_digest" c:identifier="g_hmac_get_digest" version="2.30"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="hmac" transfer-ownership="none"> + <doc xml:space="preserve">a #GHmac</doc> + <type name="Hmac" c:type="GHmac*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">output buffer</doc> + <array length="1" zero-terminated="0" c:type="guint8*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="digest_len" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">an inout parameter. The caller initializes it to the + size of @buffer. After the call it contains the length of the digest</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_string" c:identifier="g_hmac_get_string" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the hexadecimal representation of the HMAC. The + returned string is owned by the HMAC and should not be modified + or freed.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="hmac" transfer-ownership="none"> + <doc xml:space="preserve">a #GHmac</doc> + <type name="Hmac" c:type="GHmac*"/> + </instance-parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_hmac_ref" version="2.30" introspectable="0"> + <doc xml:space="preserve">Atomically increments the reference count of @hmac by one. + +This function is MT-safe and may be called from any thread.</doc> + <return-value> + <doc xml:space="preserve">the passed in #GHmac.</doc> + <type name="Hmac" c:type="GHmac*"/> + </return-value> + <parameters> + <instance-parameter name="hmac" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GHmac</doc> + <type name="Hmac" c:type="GHmac*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_hmac_unref" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="hmac" transfer-ownership="none"> + <doc xml:space="preserve">a #GHmac</doc> + <type name="Hmac" c:type="GHmac*"/> + </instance-parameter> + </parameters> + </method> + <method name="update" c:identifier="g_hmac_update" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="hmac" transfer-ownership="none"> + <doc xml:space="preserve">a #GHmac</doc> + <type name="Hmac" c:type="GHmac*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">buffer used to compute the checksum</doc> + <array length="1" zero-terminated="0" c:type="const guchar*"> + <type name="guint8" c:type="guchar"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">size of the buffer, or -1 if it is a nul-terminated string</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </method> + <function name="new" c:identifier="g_hmac_new" version="2.30" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the newly created #GHmac, or %NULL. + Use g_hmac_unref() to free the memory allocated by it.</doc> + <type name="Hmac" c:type="GHmac*"/> + </return-value> + <parameters> + <parameter name="digest_type" transfer-ownership="none"> + <doc xml:space="preserve">the desired type of digest</doc> + <type name="ChecksumType" c:type="GChecksumType"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key for the HMAC</doc> + <array length="2" zero-terminated="0" c:type="const guchar*"> + <type name="guint8" c:type="guchar"/> + </array> + </parameter> + <parameter name="key_len" transfer-ownership="none"> + <doc xml:space="preserve">the length of the keys</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + </record> + <record name="Hook" c:type="GHook"> + <doc xml:space="preserve">The #GHook struct represents a single hook function in a #GHookList.</doc> + <field name="data" writable="1"> + <doc xml:space="preserve">data which is passed to func when this hook is invoked</doc> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="next" writable="1"> + <doc xml:space="preserve">pointer to the next hook in the list</doc> + <type name="Hook" c:type="GHook*"/> + </field> + <field name="prev" writable="1"> + <doc xml:space="preserve">pointer to the previous hook in the list</doc> + <type name="Hook" c:type="GHook*"/> + </field> + <field name="ref_count" writable="1"> + <doc xml:space="preserve">the reference count of this hook</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="hook_id" writable="1"> + <doc xml:space="preserve">the id of this hook, which is unique within its list</doc> + <type name="gulong" c:type="gulong"/> + </field> + <field name="flags" writable="1"> + <doc xml:space="preserve">flags which are set for this hook. See #GHookFlagMask for + predefined flags</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="func" writable="1"> + <doc xml:space="preserve">the function to call when this hook is invoked. The possible + signatures for this function are #GHookFunc and #GHookCheckFunc</doc> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="destroy" writable="1"> + <doc xml:space="preserve">the default @finalize_hook function of a #GHookList calls + this member of the hook that is being finalized</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </field> + <method name="compare_ids" c:identifier="g_hook_compare_ids"> + <doc xml:space="preserve">Compares the ids of two #GHook elements, returning a negative value +if the second id is greater than the first.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a value <= 0 if the id of @sibling is >= the id of @new_hook</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="new_hook" transfer-ownership="none"> + <doc xml:space="preserve">a #GHook</doc> + <type name="Hook" c:type="GHook*"/> + </instance-parameter> + <parameter name="sibling" transfer-ownership="none"> + <doc xml:space="preserve">a #GHook to compare with @new_hook</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + </parameters> + </method> + <function name="alloc" c:identifier="g_hook_alloc" introspectable="0"> + <doc xml:space="preserve">Allocates space for a #GHook and initializes it.</doc> + <return-value> + <doc xml:space="preserve">a new #GHook</doc> + <type name="Hook" c:type="GHook*"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + </parameters> + </function> + <function name="destroy" c:identifier="g_hook_destroy"> + <doc xml:space="preserve">Destroys a #GHook, given its ID.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the #GHook was found in the #GHookList and destroyed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="hook_id" transfer-ownership="none"> + <doc xml:space="preserve">a hook ID</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + </parameters> + </function> + <function name="destroy_link" c:identifier="g_hook_destroy_link"> + <doc xml:space="preserve">Removes one #GHook from a #GHookList, marking it +inactive and calling g_hook_unref() on it.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">the #GHook to remove</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + </parameters> + </function> + <function name="find" c:identifier="g_hook_find" introspectable="0"> + <doc xml:space="preserve">Finds a #GHook in a #GHookList using the given function to +test for a match.</doc> + <return-value> + <doc xml:space="preserve">the found #GHook or %NULL if no matching #GHook is found</doc> + <type name="Hook" c:type="GHook*"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="need_valids" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if #GHook elements which have been destroyed + should be skipped</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="func" transfer-ownership="none" closure="3"> + <doc xml:space="preserve">the function to call for each #GHook, which should return + %TRUE when the #GHook has been found</doc> + <type name="HookFindFunc" c:type="GHookFindFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to @func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="find_data" c:identifier="g_hook_find_data" introspectable="0"> + <doc xml:space="preserve">Finds a #GHook in a #GHookList with the given data.</doc> + <return-value> + <doc xml:space="preserve">the #GHook with the given @data or %NULL if no matching + #GHook is found</doc> + <type name="Hook" c:type="GHook*"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="need_valids" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if #GHook elements which have been destroyed + should be skipped</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to find</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="find_func" c:identifier="g_hook_find_func" introspectable="0"> + <doc xml:space="preserve">Finds a #GHook in a #GHookList with the given function.</doc> + <return-value> + <doc xml:space="preserve">the #GHook with the given @func or %NULL if no matching + #GHook is found</doc> + <type name="Hook" c:type="GHook*"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="need_valids" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if #GHook elements which have been destroyed + should be skipped</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="func" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the function to find</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="find_func_data" c:identifier="g_hook_find_func_data" introspectable="0"> + <doc xml:space="preserve">Finds a #GHook in a #GHookList with the given function and data.</doc> + <return-value> + <doc xml:space="preserve">the #GHook with the given @func and @data or %NULL if + no matching #GHook is found</doc> + <type name="Hook" c:type="GHook*"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="need_valids" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if #GHook elements which have been destroyed + should be skipped</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="func" transfer-ownership="none"> + <doc xml:space="preserve">the function to find</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to find</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="first_valid" c:identifier="g_hook_first_valid" introspectable="0"> + <doc xml:space="preserve">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.)</doc> + <return-value> + <doc xml:space="preserve">the first valid #GHook, or %NULL if none are valid</doc> + <type name="Hook" c:type="GHook*"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="may_be_in_call" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if hooks which are currently running + (e.g. in another thread) are considered valid. If set to %FALSE, + these are skipped</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="free" c:identifier="g_hook_free"> + <doc xml:space="preserve">Calls the #GHookList @finalize_hook function if it exists, +and frees the memory allocated for the #GHook.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">the #GHook to free</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + </parameters> + </function> + <function name="get" c:identifier="g_hook_get" introspectable="0"> + <doc xml:space="preserve">Returns the #GHook with the given id, or %NULL if it is not found.</doc> + <return-value> + <doc xml:space="preserve">the #GHook with the given id, or %NULL if it is not found</doc> + <type name="Hook" c:type="GHook*"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="hook_id" transfer-ownership="none"> + <doc xml:space="preserve">a hook id</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + </parameters> + </function> + <function name="insert_before" c:identifier="g_hook_insert_before"> + <doc xml:space="preserve">Inserts a #GHook into a #GHookList, before a given #GHook.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="sibling" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the #GHook to insert the new #GHook before</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">the #GHook to insert</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + </parameters> + </function> + <function name="insert_sorted" c:identifier="g_hook_insert_sorted" introspectable="0"> + <doc xml:space="preserve">Inserts a #GHook into a #GHookList, sorted by the given function.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">the #GHook to insert</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + <parameter name="func" transfer-ownership="none"> + <doc xml:space="preserve">the comparison function used to sort the #GHook elements</doc> + <type name="HookCompareFunc" c:type="GHookCompareFunc"/> + </parameter> + </parameters> + </function> + <function name="next_valid" c:identifier="g_hook_next_valid" introspectable="0"> + <doc xml:space="preserve">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.)</doc> + <return-value> + <doc xml:space="preserve">the next valid #GHook, or %NULL if none are valid</doc> + <type name="Hook" c:type="GHook*"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">the current #GHook</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + <parameter name="may_be_in_call" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if hooks which are currently running + (e.g. in another thread) are considered valid. If set to %FALSE, + these are skipped</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="prepend" c:identifier="g_hook_prepend"> + <doc xml:space="preserve">Prepends a #GHook on the start of a #GHookList.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">the #GHook to add to the start of @hook_list</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + </parameters> + </function> + <function name="ref" c:identifier="g_hook_ref" introspectable="0"> + <doc xml:space="preserve">Increments the reference count for a #GHook.</doc> + <return-value> + <doc xml:space="preserve">the @hook that was passed in (since 2.6)</doc> + <type name="Hook" c:type="GHook*"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">the #GHook to increment the reference count of</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + </parameters> + </function> + <function name="unref" c:identifier="g_hook_unref"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">the #GHook to unref</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + </parameters> + </function> + </record> + <callback name="HookCheckFunc" c:type="GHookCheckFunc"> + <doc xml:space="preserve">Defines the type of a hook function that can be invoked +by g_hook_list_invoke_check().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%FALSE if the #GHook should be destroyed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data field of the #GHook is passed to the hook function here</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="HookCheckMarshaller" c:type="GHookCheckMarshaller"> + <doc xml:space="preserve">Defines the type of function used by g_hook_list_marshal_check().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%FALSE if @hook should be destroyed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">a #GHook</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="HookCompareFunc" c:type="GHookCompareFunc"> + <doc xml:space="preserve">Defines the type of function used to compare #GHook elements in +g_hook_insert_sorted().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a value <= 0 if @new_hook should be before @sibling</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="new_hook" transfer-ownership="none"> + <doc xml:space="preserve">the #GHook being inserted</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + <parameter name="sibling" transfer-ownership="none"> + <doc xml:space="preserve">the #GHook to compare with @new_hook</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + </parameters> + </callback> + <callback name="HookFinalizeFunc" c:type="GHookFinalizeFunc"> + <doc xml:space="preserve">Defines the type of function to be called when a hook in a +list of hooks gets finalized.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">the hook in @hook_list that gets finalized</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + </parameters> + </callback> + <callback name="HookFindFunc" c:type="GHookFindFunc"> + <doc xml:space="preserve">Defines the type of the function passed to g_hook_find().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the required #GHook has been found</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">a #GHook</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to g_hook_find_func()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <bitfield name="HookFlagMask" c:type="GHookFlagMask"> + <doc xml:space="preserve">Flags used internally in the #GHook implementation.</doc> + <member name="active" value="1" c:identifier="G_HOOK_FLAG_ACTIVE"> + <doc xml:space="preserve">set if the hook has not been destroyed</doc> + </member> + <member name="in_call" value="2" c:identifier="G_HOOK_FLAG_IN_CALL"> + <doc xml:space="preserve">set if the hook is currently being run</doc> + </member> + <member name="mask" value="15" c:identifier="G_HOOK_FLAG_MASK"> + <doc xml:space="preserve">A mask covering all bits reserved for + hook flags; see %G_HOOK_FLAG_USER_SHIFT</doc> + </member> + </bitfield> + <callback name="HookFunc" c:type="GHookFunc"> + <doc xml:space="preserve">Defines the type of a hook function that can be invoked +by g_hook_list_invoke().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data field of the #GHook is passed to the hook function here</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="HookList" c:type="GHookList"> + <doc xml:space="preserve">The #GHookList struct represents a list of hook functions.</doc> + <field name="seq_id" writable="1"> + <doc xml:space="preserve">the next free #GHook id</doc> + <type name="gulong" c:type="gulong"/> + </field> + <field name="hook_size" writable="1" bits="16"> + <doc xml:space="preserve">the size of the #GHookList elements, in bytes</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="is_setup" writable="1" bits="1"> + <doc xml:space="preserve">1 if the #GHookList has been initialized</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="hooks" writable="1"> + <doc xml:space="preserve">the first #GHook element in the list</doc> + <type name="Hook" c:type="GHook*"/> + </field> + <field name="dummy3" writable="1"> + <doc xml:space="preserve">unused</doc> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="finalize_hook" writable="1"> + <doc xml:space="preserve">the function to call to finalize a #GHook element. + The default behaviour is to call the hooks @destroy function</doc> + <type name="HookFinalizeFunc" c:type="GHookFinalizeFunc"/> + </field> + <field name="dummy" writable="1"> + <doc xml:space="preserve">unused</doc> + <array zero-terminated="0" fixed-size="2"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + <method name="clear" c:identifier="g_hook_list_clear"> + <doc xml:space="preserve">Removes all the #GHook elements from a #GHookList.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </instance-parameter> + </parameters> + </method> + <method name="init" c:identifier="g_hook_list_init"> + <doc xml:space="preserve">Initializes a #GHookList. +This must be called before the #GHookList is used.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </instance-parameter> + <parameter name="hook_size" transfer-ownership="none"> + <doc xml:space="preserve">the size of each element in the #GHookList, + typically `sizeof (GHook)`.</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="invoke" c:identifier="g_hook_list_invoke"> + <doc xml:space="preserve">Calls all of the #GHook functions in a #GHookList.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </instance-parameter> + <parameter name="may_recurse" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if functions which are already running + (e.g. in another thread) can be called. If set to %FALSE, + these are skipped</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="invoke_check" c:identifier="g_hook_list_invoke_check"> + <doc xml:space="preserve">Calls all of the #GHook functions in a #GHookList. +Any function which returns %FALSE is removed from the #GHookList.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </instance-parameter> + <parameter name="may_recurse" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if functions which are already running + (e.g. in another thread) can be called. If set to %FALSE, + these are skipped</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="marshal" c:identifier="g_hook_list_marshal" introspectable="0"> + <doc xml:space="preserve">Calls a function on each valid #GHook.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </instance-parameter> + <parameter name="may_recurse" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if hooks which are currently running + (e.g. in another thread) are considered valid. If set to %FALSE, + these are skipped</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="marshaller" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function to call for each #GHook</doc> + <type name="HookMarshaller" c:type="GHookMarshaller"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="marshal_check" c:identifier="g_hook_list_marshal_check" introspectable="0"> + <doc xml:space="preserve">Calls a function on each valid #GHook and destroys it if the +function returns %FALSE.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </instance-parameter> + <parameter name="may_recurse" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if hooks which are currently running + (e.g. in another thread) are considered valid. If set to %FALSE, + these are skipped</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="marshaller" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function to call for each #GHook</doc> + <type name="HookCheckMarshaller" c:type="GHookCheckMarshaller"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + </record> + <callback name="HookMarshaller" c:type="GHookMarshaller"> + <doc xml:space="preserve">Defines the type of function used by g_hook_list_marshal().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">a #GHook</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="IConv" c:type="GIConv" disguised="1" introspectable="0"> + <doc xml:space="preserve">The GIConv struct wraps an iconv() conversion descriptor. It contains +private data and should only be accessed using the following functions.</doc> + <method name="" c:identifier="g_iconv" moved-to="iconv" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">count of non-reversible conversions, or -1 on error</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="converter" transfer-ownership="none"> + <doc xml:space="preserve">conversion descriptor from g_iconv_open()</doc> + <type name="IConv" c:type="GIConv"/> + </instance-parameter> + <parameter name="inbuf" transfer-ownership="none"> + <doc xml:space="preserve">bytes to convert</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="inbytes_left" transfer-ownership="none"> + <doc xml:space="preserve">inout parameter, bytes remaining to convert in @inbuf</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="outbuf" transfer-ownership="none"> + <doc xml:space="preserve">converted output bytes</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="outbytes_left" transfer-ownership="none"> + <doc xml:space="preserve">inout parameter, bytes available to fill in @outbuf</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="close" c:identifier="g_iconv_close" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">-1 on error, 0 on success</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="converter" transfer-ownership="none"> + <doc xml:space="preserve">a conversion descriptor from g_iconv_open()</doc> + <type name="IConv" c:type="GIConv"/> + </instance-parameter> + </parameters> + </method> + <function name="open" c:identifier="g_iconv_open" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">a "conversion descriptor", or (GIConv)-1 if + opening the converter failed.</doc> + <type name="IConv" c:type="GIConv"/> + </return-value> + <parameters> + <parameter name="to_codeset" transfer-ownership="none"> + <doc xml:space="preserve">destination codeset</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="from_codeset" transfer-ownership="none"> + <doc xml:space="preserve">source codeset</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + </record> + <constant name="IEEE754_DOUBLE_BIAS" value="1023" c:type="G_IEEE754_DOUBLE_BIAS"> + <doc xml:space="preserve">The bias by which exponents in double-precision floats are offset.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="IEEE754_FLOAT_BIAS" value="127" c:type="G_IEEE754_FLOAT_BIAS"> + <doc xml:space="preserve">The bias by which exponents in single-precision floats are offset.</doc> + <type name="gint" c:type="gint"/> + </constant> + <record name="IOChannel" c:type="GIOChannel" glib:type-name="GIOChannel" glib:get-type="g_io_channel_get_type" c:symbol-prefix="io_channel"> + <doc xml:space="preserve">A data structure representing an IO Channel. The fields should be +considered private and should only be accessed with the following +functions.</doc> + <field name="ref_count" readable="0" private="1"> + <type name="gint" c:type="gint"/> + </field> + <field name="funcs" readable="0" private="1"> + <type name="IOFuncs" c:type="GIOFuncs*"/> + </field> + <field name="encoding" readable="0" private="1"> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="read_cd" introspectable="0" readable="0" private="1"> + <type name="IConv" c:type="GIConv"/> + </field> + <field name="write_cd" introspectable="0" readable="0" private="1"> + <type name="IConv" c:type="GIConv"/> + </field> + <field name="line_term" readable="0" private="1"> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="line_term_len" readable="0" private="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="buf_size" readable="0" private="1"> + <type name="gsize" c:type="gsize"/> + </field> + <field name="read_buf" readable="0" private="1"> + <type name="String" c:type="GString*"/> + </field> + <field name="encoded_read_buf" readable="0" private="1"> + <type name="String" c:type="GString*"/> + </field> + <field name="write_buf" readable="0" private="1"> + <type name="String" c:type="GString*"/> + </field> + <field name="partial_write_buf" readable="0" private="1"> + <array zero-terminated="0" fixed-size="6"> + <type name="gchar" c:type="gchar"/> + </array> + </field> + <field name="use_buffer" readable="0" bits="1" private="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="do_encode" readable="0" bits="1" private="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="close_on_unref" readable="0" bits="1" private="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="is_readable" readable="0" bits="1" private="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="is_writeable" readable="0" bits="1" private="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="is_seekable" readable="0" bits="1" private="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="reserved1" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="reserved2" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <constructor name="new_file" c:identifier="g_io_channel_new_file" throws="1"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GIOChannel on success, %NULL on failure.</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">A string containing the name of a file</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve">One of "r", "w", "a", "r+", "w+", "a+". These have + the same meaning as in fopen()</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="unix_new" c:identifier="g_io_channel_unix_new"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GIOChannel.</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </return-value> + <parameters> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a file descriptor.</doc> + <type name="gint" c:type="int"/> + </parameter> + </parameters> + </constructor> + <method name="close" c:identifier="g_io_channel_close" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">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().</doc> + <doc-deprecated xml:space="preserve">Use g_io_channel_shutdown() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">A #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + </parameters> + </method> + <method name="flush" c:identifier="g_io_channel_flush" throws="1"> + <doc xml:space="preserve">Flushes the write buffer for the GIOChannel.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the status of the operation: One of + #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or + #G_IO_STATUS_ERROR.</doc> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_buffer_condition" c:identifier="g_io_channel_get_buffer_condition"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A #GIOCondition</doc> + <type name="IOCondition" c:type="GIOCondition"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">A #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_buffer_size" c:identifier="g_io_channel_get_buffer_size"> + <doc xml:space="preserve">Gets the buffer size.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the size of the buffer.</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_buffered" c:identifier="g_io_channel_get_buffered"> + <doc xml:space="preserve">Returns whether @channel is buffered.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @channel is buffered.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_close_on_unref" c:identifier="g_io_channel_get_close_on_unref"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the channel will be closed, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel.</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_encoding" c:identifier="g_io_channel_get_encoding"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A string containing the encoding, this string is + owned by GLib and must not be freed.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_flags" c:identifier="g_io_channel_get_flags"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the flags which are set on the channel</doc> + <type name="IOFlags" c:type="GIOFlags"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_line_term" c:identifier="g_io_channel_get_line_term"> + <doc xml:space="preserve">This returns the string that #GIOChannel uses to determine +where in the file a line break occurs. A value of %NULL +indicates autodetection.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The line termination string. This value + is owned by GLib and must not be freed.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">a location to return the length of the line terminator</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </method> + <method name="init" c:identifier="g_io_channel_init"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + </parameters> + </method> + <method name="read" c:identifier="g_io_channel_read" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">Reads data from a #GIOChannel.</doc> + <doc-deprecated xml:space="preserve">Use g_io_channel_read_chars() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%G_IO_ERROR_NONE if the operation was successful.</doc> + <type name="IOError" c:type="GIOError"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="buf" transfer-ownership="none"> + <doc xml:space="preserve">a buffer to read the data into (which should be at least + count bytes long)</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to read from the #GIOChannel</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="bytes_read" transfer-ownership="none"> + <doc xml:space="preserve">returns the number of bytes actually read</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="read_chars" c:identifier="g_io_channel_read_chars" throws="1"> + <doc xml:space="preserve">Replacement for g_io_channel_read() with the new API.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the status of the operation.</doc> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="buf" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve"> + a buffer to read data into</doc> + <array length="1" zero-terminated="0" c:type="gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the size of the buffer. Note that the buffer may not be + completely filled even if there is data in the buffer if the + remaining data is not a complete character.</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">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.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="read_line" c:identifier="g_io_channel_read_line" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the status of the operation.</doc> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="str_return" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store length of the read data, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="terminator_pos" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store position of line terminator, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="read_line_string" c:identifier="g_io_channel_read_line_string" throws="1"> + <doc xml:space="preserve">Reads a line from a #GIOChannel, using a #GString as a buffer.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the status of the operation.</doc> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">a #GString into which the line will be written. + If @buffer already contains data, the old data will + be overwritten.</doc> + <type name="String" c:type="GString*"/> + </parameter> + <parameter name="terminator_pos" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">location to store position of line terminator, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="read_to_end" c:identifier="g_io_channel_read_to_end" throws="1"> + <doc xml:space="preserve">Reads all the remaining data from the file.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%G_IO_STATUS_NORMAL on success. + This function never returns %G_IO_STATUS_EOF.</doc> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="str_return" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <array length="1" zero-terminated="0" c:type="gchar**"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">location to store length of the data</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="read_unichar" c:identifier="g_io_channel_read_unichar" throws="1"> + <doc xml:space="preserve">Reads a Unicode character from @channel. +This function cannot be called on a channel with %NULL encoding.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStatus</doc> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="thechar" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">a location to return a character</doc> + <type name="gunichar" c:type="gunichar*"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_io_channel_ref"> + <doc xml:space="preserve">Increments the reference count of a #GIOChannel.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the @channel that was passed in (since 2.6)</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + </parameters> + </method> + <method name="seek" c:identifier="g_io_channel_seek" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">Sets the current position in the #GIOChannel, similar to the standard +library function fseek().</doc> + <doc-deprecated xml:space="preserve">Use g_io_channel_seek_position() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%G_IO_ERROR_NONE if the operation was successful.</doc> + <type name="IOError" c:type="GIOError"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="offset" transfer-ownership="none"> + <doc xml:space="preserve">an offset, in bytes, which is added to the position specified + by @type</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">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)</doc> + <type name="SeekType" c:type="GSeekType"/> + </parameter> + </parameters> + </method> + <method name="seek_position" c:identifier="g_io_channel_seek_position" throws="1"> + <doc xml:space="preserve">Replacement for g_io_channel_seek() with the new API.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the status of the operation.</doc> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="offset" transfer-ownership="none"> + <doc xml:space="preserve">The offset in bytes from the position specified by @type</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="SeekType" c:type="GSeekType"/> + </parameter> + </parameters> + </method> + <method name="set_buffer_size" c:identifier="g_io_channel_set_buffer_size"> + <doc xml:space="preserve">Sets the buffer size.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">the size of the buffer, or 0 to let GLib pick a good size</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <method name="set_buffered" c:identifier="g_io_channel_set_buffered"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="buffered" transfer-ownership="none"> + <doc xml:space="preserve">whether to set the channel buffered or unbuffered</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_close_on_unref" c:identifier="g_io_channel_set_close_on_unref"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="do_close" transfer-ownership="none"> + <doc xml:space="preserve">Whether to close the channel on the final unref of + the GIOChannel data structure.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_encoding" c:identifier="g_io_channel_set_encoding" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%G_IO_STATUS_NORMAL if the encoding was successfully set</doc> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="encoding" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the encoding type</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_flags" c:identifier="g_io_channel_set_flags" throws="1"> + <doc xml:space="preserve">Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the status of the operation.</doc> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">the flags to set on the IO channel</doc> + <type name="IOFlags" c:type="GIOFlags"/> + </parameter> + </parameters> + </method> + <method name="set_line_term" c:identifier="g_io_channel_set_line_term"> + <doc xml:space="preserve">This sets the string that #GIOChannel uses to determine +where in the file a line break occurs.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="line_term" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="shutdown" c:identifier="g_io_channel_shutdown" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the status of the operation.</doc> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="flush" transfer-ownership="none"> + <doc xml:space="preserve">if %TRUE, flush pending</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="unix_get_fd" c:identifier="g_io_channel_unix_get_fd"> + <doc xml:space="preserve">Returns the file descriptor of the #GIOChannel. + +On Windows this function returns the file descriptor or socket of +the #GIOChannel.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the file descriptor of the #GIOChannel.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel, created with g_io_channel_unix_new().</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_io_channel_unref"> + <doc xml:space="preserve">Decrements the reference count of a #GIOChannel.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + </parameters> + </method> + <method name="write" c:identifier="g_io_channel_write" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">Writes data to a #GIOChannel.</doc> + <doc-deprecated xml:space="preserve">Use g_io_channel_write_chars() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%G_IO_ERROR_NONE if the operation was successful.</doc> + <type name="IOError" c:type="GIOError"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="buf" transfer-ownership="none"> + <doc xml:space="preserve">the buffer containing the data to write</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="bytes_written" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes actually written</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="write_chars" c:identifier="g_io_channel_write_chars" throws="1"> + <doc xml:space="preserve">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 ().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the status of the operation.</doc> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="buf" transfer-ownership="none"> + <doc xml:space="preserve">a buffer to write data from</doc> + <array zero-terminated="0" c:type="const gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the size of the buffer. If -1, the buffer + is taken to be a nul-terminated string.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="write_unichar" c:identifier="g_io_channel_write_unichar" throws="1"> + <doc xml:space="preserve">Writes a Unicode character to @channel. +This function cannot be called on a channel with %NULL encoding.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStatus</doc> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <instance-parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </instance-parameter> + <parameter name="thechar" transfer-ownership="none"> + <doc xml:space="preserve">a character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </method> + <function name="error_from_errno" c:identifier="g_io_channel_error_from_errno"> + <doc xml:space="preserve">Converts an `errno` error number to a #GIOChannelError.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannelError error number, e.g. + %G_IO_CHANNEL_ERROR_INVAL.</doc> + <type name="IOChannelError" c:type="GIOChannelError"/> + </return-value> + <parameters> + <parameter name="en" transfer-ownership="none"> + <doc xml:space="preserve">an `errno` error number, e.g. `EINVAL`</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="error_quark" c:identifier="g_io_channel_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + </record> + <enumeration name="IOChannelError" c:type="GIOChannelError" glib:error-domain="g-io-channel-error-quark"> + <doc xml:space="preserve">Error codes returned by #GIOChannel operations.</doc> + <member name="fbig" value="0" c:identifier="G_IO_CHANNEL_ERROR_FBIG"> + <doc xml:space="preserve">File too large.</doc> + </member> + <member name="inval" value="1" c:identifier="G_IO_CHANNEL_ERROR_INVAL"> + <doc xml:space="preserve">Invalid argument.</doc> + </member> + <member name="io" value="2" c:identifier="G_IO_CHANNEL_ERROR_IO"> + <doc xml:space="preserve">IO error.</doc> + </member> + <member name="isdir" value="3" c:identifier="G_IO_CHANNEL_ERROR_ISDIR"> + <doc xml:space="preserve">File is a directory.</doc> + </member> + <member name="nospc" value="4" c:identifier="G_IO_CHANNEL_ERROR_NOSPC"> + <doc xml:space="preserve">No space left on device.</doc> + </member> + <member name="nxio" value="5" c:identifier="G_IO_CHANNEL_ERROR_NXIO"> + <doc xml:space="preserve">No such device or address.</doc> + </member> + <member name="overflow" value="6" c:identifier="G_IO_CHANNEL_ERROR_OVERFLOW"> + <doc xml:space="preserve">Value too large for defined datatype.</doc> + </member> + <member name="pipe" value="7" c:identifier="G_IO_CHANNEL_ERROR_PIPE"> + <doc xml:space="preserve">Broken pipe.</doc> + </member> + <member name="failed" value="8" c:identifier="G_IO_CHANNEL_ERROR_FAILED"> + <doc xml:space="preserve">Some other error.</doc> + </member> + </enumeration> + <bitfield name="IOCondition" glib:type-name="GIOCondition" glib:get-type="g_io_condition_get_type" c:type="GIOCondition"> + <doc xml:space="preserve">A bitwise combination representing a condition to watch for on an +event source.</doc> + <member name="in" value="1" c:identifier="G_IO_IN" glib:nick="in"> + <doc xml:space="preserve">There is data to read.</doc> + </member> + <member name="out" value="4" c:identifier="G_IO_OUT" glib:nick="out"> + <doc xml:space="preserve">Data can be written (without blocking).</doc> + </member> + <member name="pri" value="2" c:identifier="G_IO_PRI" glib:nick="pri"> + <doc xml:space="preserve">There is urgent data to read.</doc> + </member> + <member name="err" value="8" c:identifier="G_IO_ERR" glib:nick="err"> + <doc xml:space="preserve">Error condition.</doc> + </member> + <member name="hup" value="16" c:identifier="G_IO_HUP" glib:nick="hup"> + <doc xml:space="preserve">Hung up (the connection has been broken, usually for + pipes and sockets).</doc> + </member> + <member name="nval" value="32" c:identifier="G_IO_NVAL" glib:nick="nval"> + <doc xml:space="preserve">Invalid request. The file descriptor is not open.</doc> + </member> + </bitfield> + <enumeration name="IOError" c:type="GIOError"> + <doc xml:space="preserve">#GIOError is only used by the deprecated functions +g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek().</doc> + <member name="none" value="0" c:identifier="G_IO_ERROR_NONE"> + <doc xml:space="preserve">no error</doc> + </member> + <member name="again" value="1" c:identifier="G_IO_ERROR_AGAIN"> + <doc xml:space="preserve">an EAGAIN error occurred</doc> + </member> + <member name="inval" value="2" c:identifier="G_IO_ERROR_INVAL"> + <doc xml:space="preserve">an EINVAL error occurred</doc> + </member> + <member name="unknown" value="3" c:identifier="G_IO_ERROR_UNKNOWN"> + <doc xml:space="preserve">another error occurred</doc> + </member> + </enumeration> + <bitfield name="IOFlags" c:type="GIOFlags"> + <doc xml:space="preserve">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().</doc> + <member name="append" value="1" c:identifier="G_IO_FLAG_APPEND"> + <doc xml:space="preserve">turns on append mode, corresponds to %O_APPEND + (see the documentation of the UNIX open() syscall)</doc> + </member> + <member name="nonblock" value="2" c:identifier="G_IO_FLAG_NONBLOCK"> + <doc xml:space="preserve">turns on nonblocking mode, corresponds to + %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open() + syscall)</doc> + </member> + <member name="is_readable" value="4" c:identifier="G_IO_FLAG_IS_READABLE"> + <doc xml:space="preserve">indicates that the io channel is readable. + This flag cannot be changed.</doc> + </member> + <member name="is_writable" value="8" c:identifier="G_IO_FLAG_IS_WRITABLE"> + <doc xml:space="preserve">indicates that the io channel is writable. + This flag cannot be changed.</doc> + </member> + <member name="is_writeable" value="8" c:identifier="G_IO_FLAG_IS_WRITEABLE"> + <doc xml:space="preserve">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</doc> + </member> + <member name="is_seekable" value="16" c:identifier="G_IO_FLAG_IS_SEEKABLE"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="mask" value="31" c:identifier="G_IO_FLAG_MASK"> + <doc xml:space="preserve">the mask that specifies all the valid flags.</doc> + </member> + <member name="get_mask" value="31" c:identifier="G_IO_FLAG_GET_MASK"> + <doc xml:space="preserve">the mask of the flags that are returned from + g_io_channel_get_flags()</doc> + </member> + <member name="set_mask" value="3" c:identifier="G_IO_FLAG_SET_MASK"> + <doc xml:space="preserve">the mask of the flags that the user can modify + with g_io_channel_set_flags()</doc> + </member> + </bitfield> + <callback name="IOFunc" c:type="GIOFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the function should return %FALSE if the event source + should be removed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">the #GIOChannel event source</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">the condition which has been satisfied</doc> + <type name="IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data set in g_io_add_watch() or g_io_add_watch_full()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="IOFuncs" c:type="GIOFuncs"> + <doc xml:space="preserve">A table of functions used to handle different types of #GIOChannel +in a generic way.</doc> + <field name="io_read"> + <callback name="io_read" throws="1"> + <return-value transfer-ownership="none"> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <parameter name="channel" transfer-ownership="none"> + <type name="IOChannel" c:type="GIOChannel*"/> + </parameter> + <parameter name="buf" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="count" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="bytes_read" transfer-ownership="none"> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="io_write"> + <callback name="io_write" throws="1"> + <return-value transfer-ownership="none"> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <parameter name="channel" transfer-ownership="none"> + <type name="IOChannel" c:type="GIOChannel*"/> + </parameter> + <parameter name="buf" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="count" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="bytes_written" transfer-ownership="none"> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="io_seek"> + <callback name="io_seek" throws="1"> + <return-value transfer-ownership="none"> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <parameter name="channel" transfer-ownership="none"> + <type name="IOChannel" c:type="GIOChannel*"/> + </parameter> + <parameter name="offset" transfer-ownership="none"> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <type name="SeekType" c:type="GSeekType"/> + </parameter> + </parameters> + </callback> + </field> + <field name="io_close"> + <callback name="io_close" throws="1"> + <return-value transfer-ownership="none"> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <parameter name="channel" transfer-ownership="none"> + <type name="IOChannel" c:type="GIOChannel*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="io_create_watch"> + <callback name="io_create_watch"> + <return-value transfer-ownership="full"> + <type name="Source" c:type="GSource*"/> + </return-value> + <parameters> + <parameter name="channel" transfer-ownership="none"> + <type name="IOChannel" c:type="GIOChannel*"/> + </parameter> + <parameter name="condition" transfer-ownership="none"> + <type name="IOCondition" c:type="GIOCondition"/> + </parameter> + </parameters> + </callback> + </field> + <field name="io_free"> + <callback name="io_free"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="channel" transfer-ownership="none"> + <type name="IOChannel" c:type="GIOChannel*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="io_set_flags"> + <callback name="io_set_flags" throws="1"> + <return-value transfer-ownership="none"> + <type name="IOStatus" c:type="GIOStatus"/> + </return-value> + <parameters> + <parameter name="channel" transfer-ownership="none"> + <type name="IOChannel" c:type="GIOChannel*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <type name="IOFlags" c:type="GIOFlags"/> + </parameter> + </parameters> + </callback> + </field> + <field name="io_get_flags"> + <callback name="io_get_flags"> + <return-value transfer-ownership="none"> + <type name="IOFlags" c:type="GIOFlags"/> + </return-value> + <parameters> + <parameter name="channel" transfer-ownership="none"> + <type name="IOChannel" c:type="GIOChannel*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <enumeration name="IOStatus" c:type="GIOStatus"> + <doc xml:space="preserve">Statuses returned by most of the #GIOFuncs functions.</doc> + <member name="error" value="0" c:identifier="G_IO_STATUS_ERROR"> + <doc xml:space="preserve">An error occurred.</doc> + </member> + <member name="normal" value="1" c:identifier="G_IO_STATUS_NORMAL"> + <doc xml:space="preserve">Success.</doc> + </member> + <member name="eof" value="2" c:identifier="G_IO_STATUS_EOF"> + <doc xml:space="preserve">End of file.</doc> + </member> + <member name="again" value="3" c:identifier="G_IO_STATUS_AGAIN"> + <doc xml:space="preserve">Resource temporarily unavailable.</doc> + </member> + </enumeration> + <function-macro name="IS_DIR_SEPARATOR" c:identifier="G_IS_DIR_SEPARATOR" version="2.6" introspectable="0"> + <doc xml:space="preserve">Checks whether a character is a directory +separator. It returns %TRUE for '/' on UNIX +machines and for '\' or '/' under Windows.</doc> + <parameters> + <parameter name="c"> + <doc xml:space="preserve">a character</doc> + </parameter> + </parameters> + </function-macro> + <constant name="KEY_FILE_DESKTOP_GROUP" value="Desktop Entry" c:type="G_KEY_FILE_DESKTOP_GROUP" version="2.14"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_ACTIONS" value="Actions" c:type="G_KEY_FILE_DESKTOP_KEY_ACTIONS" version="2.38"> + <doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string list +giving the available application actions.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_CATEGORIES" value="Categories" c:type="G_KEY_FILE_DESKTOP_KEY_CATEGORIES" version="2.14"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_COMMENT" value="Comment" c:type="G_KEY_FILE_DESKTOP_KEY_COMMENT" version="2.14"> + <doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized +string giving the tooltip for the desktop entry.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE" value="DBusActivatable" c:type="G_KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE" version="2.38"> + <doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean set to true +if the application is D-Bus activatable.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_EXEC" value="Exec" c:type="G_KEY_FILE_DESKTOP_KEY_EXEC" version="2.14"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_GENERIC_NAME" value="GenericName" c:type="G_KEY_FILE_DESKTOP_KEY_GENERIC_NAME" version="2.14"> + <doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized +string giving the generic name of the desktop entry.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_HIDDEN" value="Hidden" c:type="G_KEY_FILE_DESKTOP_KEY_HIDDEN" version="2.14"> + <doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean +stating whether the desktop entry has been deleted by the user.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_ICON" value="Icon" c:type="G_KEY_FILE_DESKTOP_KEY_ICON" version="2.14"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_MIME_TYPE" value="MimeType" c:type="G_KEY_FILE_DESKTOP_KEY_MIME_TYPE" version="2.14"> + <doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list +of strings giving the MIME types supported by this desktop entry.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_NAME" value="Name" c:type="G_KEY_FILE_DESKTOP_KEY_NAME" version="2.14"> + <doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized +string giving the specific name of the desktop entry.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN" value="NotShowIn" c:type="G_KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN" version="2.14"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_NO_DISPLAY" value="NoDisplay" c:type="G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY" version="2.14"> + <doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean +stating whether the desktop entry should be shown in menus.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN" value="OnlyShowIn" c:type="G_KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN" version="2.14"> + <doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of +strings identifying the environments that should display the +desktop entry.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_PATH" value="Path" c:type="G_KEY_FILE_DESKTOP_KEY_PATH" version="2.14"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY" value="StartupNotify" c:type="G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY" version="2.14"> + <doc xml:space="preserve">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).</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS" value="StartupWMClass" c:type="G_KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS" version="2.14"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_TERMINAL" value="Terminal" c:type="G_KEY_FILE_DESKTOP_KEY_TERMINAL" version="2.14"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_TRY_EXEC" value="TryExec" c:type="G_KEY_FILE_DESKTOP_KEY_TRY_EXEC" version="2.14"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_TYPE" value="Type" c:type="G_KEY_FILE_DESKTOP_KEY_TYPE" version="2.14"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_URL" value="URL" c:type="G_KEY_FILE_DESKTOP_KEY_URL" version="2.14"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_KEY_VERSION" value="Version" c:type="G_KEY_FILE_DESKTOP_KEY_VERSION" version="2.14"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_TYPE_APPLICATION" value="Application" c:type="G_KEY_FILE_DESKTOP_TYPE_APPLICATION" version="2.14"> + <doc xml:space="preserve">The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop +entries representing applications.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_TYPE_DIRECTORY" value="Directory" c:type="G_KEY_FILE_DESKTOP_TYPE_DIRECTORY" version="2.14"> + <doc xml:space="preserve">The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop +entries representing directories.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="KEY_FILE_DESKTOP_TYPE_LINK" value="Link" c:type="G_KEY_FILE_DESKTOP_TYPE_LINK" version="2.14"> + <doc xml:space="preserve">The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop +entries representing links to documents.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <record name="KeyFile" c:type="GKeyFile" glib:type-name="GKeyFile" glib:get-type="g_key_file_get_type" c:symbol-prefix="key_file"> + <doc xml:space="preserve">The GKeyFile struct contains only private data +and should not be accessed directly.</doc> + <constructor name="new" c:identifier="g_key_file_new" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an empty #GKeyFile.</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </return-value> + </constructor> + <method name="free" c:identifier="g_key_file_free" version="2.6" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_boolean" c:identifier="g_key_file_get_boolean" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value associated with the key as a boolean, + or %FALSE if the key was not found or could not be parsed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_boolean_list" c:identifier="g_key_file_get_boolean_list" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="container"> + <doc xml:space="preserve"> + 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.</doc> + <array length="2" zero-terminated="0" c:type="gboolean*"> + <type name="gboolean"/> + </array> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the number of booleans returned</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_comment" c:identifier="g_key_file_get_comment" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a comment that should be freed with g_free()</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a group name, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_double" c:identifier="g_key_file_get_double" version="2.12" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value associated with the key as a double, or + 0.0 if the key was not found or could not be parsed.</doc> + <type name="gdouble" c:type="gdouble"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_double_list" c:identifier="g_key_file_get_double_list" version="2.12" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="container"> + <doc xml:space="preserve"> + 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.</doc> + <array length="2" zero-terminated="0" c:type="gdouble*"> + <type name="gdouble"/> + </array> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the number of doubles returned</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_groups" c:identifier="g_key_file_get_groups" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated %NULL-terminated array of strings. + Use g_strfreev() to free it.</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the number of returned groups, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_int64" c:identifier="g_key_file_get_int64" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint64" c:type="gint64"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a non-%NULL #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a non-%NULL group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a non-%NULL key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_integer" c:identifier="g_key_file_get_integer" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value associated with the key as an integer, or + 0 if the key was not found or could not be parsed.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_integer_list" c:identifier="g_key_file_get_integer_list" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="container"> + <doc xml:space="preserve"> + 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.</doc> + <array length="2" zero-terminated="0" c:type="gint*"> + <type name="gint"/> + </array> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the number of integers returned</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_keys" c:identifier="g_key_file_get_keys" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated %NULL-terminated array of strings. + Use g_strfreev() to free it.</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the number of keys returned, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_locale_for_key" c:identifier="g_key_file_get_locale_for_key" version="2.56"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the locale from the file, or %NULL if the key was not + found or the entry in the file was was untranslated</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="locale" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a locale identifier or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_locale_string" c:identifier="g_key_file_get_locale_string" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string or %NULL if the specified + key cannot be found.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="locale" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a locale identifier or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_locale_string_list" c:identifier="g_key_file_get_locale_string_list" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated %NULL-terminated string array + or %NULL if the key isn't found. The string array should be freed + with g_strfreev().</doc> + <array length="3" zero-terminated="1" c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="locale" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a locale identifier or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the number of returned strings or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_start_group" c:identifier="g_key_file_get_start_group" version="2.6"> + <doc xml:space="preserve">Returns the name of the start group of the file.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">The start group of the key file.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_string" c:identifier="g_key_file_get_string" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string or %NULL if the specified + key cannot be found.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_string_list" c:identifier="g_key_file_get_string_list" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + a %NULL-terminated string array or %NULL if the specified + key cannot be found. The array should be freed with g_strfreev().</doc> + <array length="2" zero-terminated="1" c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the number of returned strings, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_uint64" c:identifier="g_key_file_get_uint64" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="guint64" c:type="guint64"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a non-%NULL #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a non-%NULL group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a non-%NULL key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_value" c:identifier="g_key_file_get_value" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string or %NULL if the specified + key cannot be found.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="has_group" c:identifier="g_key_file_has_group" version="2.6"> + <doc xml:space="preserve">Looks whether the key file has the group @group_name.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @group_name is a part of @key_file, %FALSE +otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="has_key" c:identifier="g_key_file_has_key" version="2.6" introspectable="0" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @key is a part of @group_name, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="load_from_bytes" c:identifier="g_key_file_load_from_bytes" version="2.50" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a key file could be loaded, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">an empty #GKeyFile struct</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="bytes" transfer-ownership="none"> + <doc xml:space="preserve">a #GBytes</doc> + <type name="Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags from #GKeyFileFlags</doc> + <type name="KeyFileFlags" c:type="GKeyFileFlags"/> + </parameter> + </parameters> + </method> + <method name="load_from_data" c:identifier="g_key_file_load_from_data" version="2.6" throws="1"> + <doc xml:space="preserve">Loads a key file from memory into an empty #GKeyFile structure. +If the object cannot be created then %error is set to a #GKeyFileError.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a key file could be loaded, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">an empty #GKeyFile struct</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">key file loaded in memory</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @data in bytes (or (gsize)-1 if data is nul-terminated)</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags from #GKeyFileFlags</doc> + <type name="KeyFileFlags" c:type="GKeyFileFlags"/> + </parameter> + </parameters> + </method> + <method name="load_from_data_dirs" c:identifier="g_key_file_load_from_data_dirs" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a key file could be loaded, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">an empty #GKeyFile struct</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a relative path to a filename to open and parse</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="full_path" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for a string containing the full path + of the file, or %NULL</doc> + <type name="filename" c:type="gchar**"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags from #GKeyFileFlags</doc> + <type name="KeyFileFlags" c:type="GKeyFileFlags"/> + </parameter> + </parameters> + </method> + <method name="load_from_dirs" c:identifier="g_key_file_load_from_dirs" version="2.14" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a key file could be loaded, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">an empty #GKeyFile struct</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a relative path to a filename to open and parse</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="search_dirs" transfer-ownership="none"> + <doc xml:space="preserve">%NULL-terminated array of directories to search</doc> + <array c:type="const gchar**"> + <type name="filename"/> + </array> + </parameter> + <parameter name="full_path" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for a string containing the full path + of the file, or %NULL</doc> + <type name="filename" c:type="gchar**"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags from #GKeyFileFlags</doc> + <type name="KeyFileFlags" c:type="GKeyFileFlags"/> + </parameter> + </parameters> + </method> + <method name="load_from_file" c:identifier="g_key_file_load_from_file" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a key file could be loaded, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">an empty #GKeyFile struct</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">the path of a filename to load, in the GLib filename encoding</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags from #GKeyFileFlags</doc> + <type name="KeyFileFlags" c:type="GKeyFileFlags"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_key_file_ref" version="2.32" introspectable="0"> + <doc xml:space="preserve">Increases the reference count of @key_file.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the same @key_file.</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="remove_comment" c:identifier="g_key_file_remove_comment" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the comment was removed, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a group name, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="remove_group" c:identifier="g_key_file_remove_group" version="2.6" throws="1"> + <doc xml:space="preserve">Removes the specified group, @group_name, +from the key file.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the group was removed, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="remove_key" c:identifier="g_key_file_remove_key" version="2.6" throws="1"> + <doc xml:space="preserve">Removes @key in @group_name from the key file.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key was removed, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key name to remove</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="save_to_file" c:identifier="g_key_file_save_to_file" version="2.40" throws="1"> + <doc xml:space="preserve">Writes the contents of @key_file to @filename using +g_file_set_contents(). If you need stricter guarantees about durability of +the written file than are provided by g_file_set_contents(), use +g_file_set_contents_full() with the return value of g_key_file_to_data(). + +This function can fail for any of the reasons that +g_file_set_contents() may fail.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful, else %FALSE with @error set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">the name of the file to write to</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_boolean" c:identifier="g_key_file_set_boolean" version="2.6"> + <doc xml:space="preserve">Associates a new boolean value with @key under @group_name. +If @key cannot be found then it is created.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE or %FALSE</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_boolean_list" c:identifier="g_key_file_set_boolean_list" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">an array of boolean values</doc> + <array length="3" zero-terminated="0" c:type="gboolean*"> + <type name="gboolean" c:type="gboolean"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">length of @list</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <method name="set_comment" c:identifier="g_key_file_set_comment" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the comment was written, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a group name, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="comment" transfer-ownership="none"> + <doc xml:space="preserve">a comment</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_double" c:identifier="g_key_file_set_double" version="2.12"> + <doc xml:space="preserve">Associates a new double value with @key under @group_name. +If @key cannot be found then it is created.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a double value</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + </parameters> + </method> + <method name="set_double_list" c:identifier="g_key_file_set_double_list" version="2.12"> + <doc xml:space="preserve">Associates a list of double values with @key under +@group_name. If @key cannot be found then it is created.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">an array of double values</doc> + <array length="3" zero-terminated="0" c:type="gdouble*"> + <type name="gdouble" c:type="gdouble"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">number of double values in @list</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <method name="set_int64" c:identifier="g_key_file_set_int64" version="2.26"> + <doc xml:space="preserve">Associates a new integer value with @key under @group_name. +If @key cannot be found then it is created.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">an integer value</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + </parameters> + </method> + <method name="set_integer" c:identifier="g_key_file_set_integer" version="2.6"> + <doc xml:space="preserve">Associates a new integer value with @key under @group_name. +If @key cannot be found then it is created.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">an integer value</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="set_integer_list" c:identifier="g_key_file_set_integer_list" version="2.6"> + <doc xml:space="preserve">Associates a list of integer values with @key under @group_name. +If @key cannot be found then it is created.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">an array of integer values</doc> + <array length="3" zero-terminated="0" c:type="gint*"> + <type name="gint" c:type="gint"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">number of integer values in @list</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <method name="set_list_separator" c:identifier="g_key_file_set_list_separator" version="2.6"> + <doc xml:space="preserve">Sets the character which is used to separate +values in lists. Typically ';' or ',' are used +as separators. The default list separator is ';'.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="separator" transfer-ownership="none"> + <doc xml:space="preserve">the separator</doc> + <type name="gchar" c:type="gchar"/> + </parameter> + </parameters> + </method> + <method name="set_locale_string" c:identifier="g_key_file_set_locale_string" version="2.6"> + <doc xml:space="preserve">Associates a string value for @key and @locale under @group_name. +If the translation for @key cannot be found then it is created.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="locale" transfer-ownership="none"> + <doc xml:space="preserve">a locale identifier</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_locale_string_list" c:identifier="g_key_file_set_locale_string_list" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="locale" transfer-ownership="none"> + <doc xml:space="preserve">a locale identifier</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a %NULL-terminated array of locale string values</doc> + <array length="4" zero-terminated="1" c:type="const gchar* const*"> + <type name="utf8" c:type="gchar*"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @list</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <method name="set_string" c:identifier="g_key_file_set_string" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_string_list" c:identifier="g_key_file_set_string_list" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">an array of string values</doc> + <array length="3" zero-terminated="1" c:type="const gchar* const*"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">number of string values in @list</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <method name="set_uint64" c:identifier="g_key_file_set_uint64" version="2.26"> + <doc xml:space="preserve">Associates a new integer value with @key under @group_name. +If @key cannot be found then it is created.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">an integer value</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + </parameters> + </method> + <method name="set_value" c:identifier="g_key_file_set_value" version="2.6"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="group_name" transfer-ownership="none"> + <doc xml:space="preserve">a group name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="to_data" c:identifier="g_key_file_to_data" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string holding + the contents of the #GKeyFile</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the length of the + returned string, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_key_file_unref" version="2.32"> + <doc xml:space="preserve">Decreases the reference count of @key_file by 1. If the reference count +reaches zero, frees the key file and all its allocated memory.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GKeyFile</doc> + <type name="KeyFile" c:type="GKeyFile*"/> + </instance-parameter> + </parameters> + </method> + <function name="error_quark" c:identifier="g_key_file_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + </record> + <enumeration name="KeyFileError" c:type="GKeyFileError" glib:error-domain="g-key-file-error-quark"> + <doc xml:space="preserve">Error codes returned by key file parsing.</doc> + <member name="unknown_encoding" value="0" c:identifier="G_KEY_FILE_ERROR_UNKNOWN_ENCODING"> + <doc xml:space="preserve">the text being parsed was in + an unknown encoding</doc> + </member> + <member name="parse" value="1" c:identifier="G_KEY_FILE_ERROR_PARSE"> + <doc xml:space="preserve">document was ill-formed</doc> + </member> + <member name="not_found" value="2" c:identifier="G_KEY_FILE_ERROR_NOT_FOUND"> + <doc xml:space="preserve">the file was not found</doc> + </member> + <member name="key_not_found" value="3" c:identifier="G_KEY_FILE_ERROR_KEY_NOT_FOUND"> + <doc xml:space="preserve">a requested key was not found</doc> + </member> + <member name="group_not_found" value="4" c:identifier="G_KEY_FILE_ERROR_GROUP_NOT_FOUND"> + <doc xml:space="preserve">a requested group was not found</doc> + </member> + <member name="invalid_value" value="5" c:identifier="G_KEY_FILE_ERROR_INVALID_VALUE"> + <doc xml:space="preserve">a value could not be parsed</doc> + </member> + </enumeration> + <bitfield name="KeyFileFlags" c:type="GKeyFileFlags"> + <doc xml:space="preserve">Flags which influence the parsing.</doc> + <member name="none" value="0" c:identifier="G_KEY_FILE_NONE"> + <doc xml:space="preserve">No flags, default behaviour</doc> + </member> + <member name="keep_comments" value="1" c:identifier="G_KEY_FILE_KEEP_COMMENTS"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="keep_translations" value="2" c:identifier="G_KEY_FILE_KEEP_TRANSLATIONS"> + <doc xml:space="preserve">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.</doc> + </member> + </bitfield> + <function-macro name="LIKELY" c:identifier="G_LIKELY" version="2.2" introspectable="0"> + <doc xml:space="preserve">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"); +]|</doc> + <parameters> + <parameter name="expr"> + <doc xml:space="preserve">the expression</doc> + </parameter> + </parameters> + </function-macro> + <constant name="LITTLE_ENDIAN" value="1234" c:type="G_LITTLE_ENDIAN"> + <doc xml:space="preserve">Specifies one of the possible types of byte order. +See #G_BYTE_ORDER.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="LN10" value="2.302585" c:type="G_LN10"> + <doc xml:space="preserve">The natural logarithm of 10.</doc> + <type name="gdouble" c:type="gdouble"/> + </constant> + <constant name="LN2" value="0.693147" c:type="G_LN2"> + <doc xml:space="preserve">The natural logarithm of 2.</doc> + <type name="gdouble" c:type="gdouble"/> + </constant> + <function-macro name="LOCK" c:identifier="G_LOCK" introspectable="0"> + <doc xml:space="preserve">Works like g_mutex_lock(), but for a lock defined with +#G_LOCK_DEFINE.</doc> + <parameters> + <parameter name="name"> + <doc xml:space="preserve">the name of the lock</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="LOCK_DEFINE" c:identifier="G_LOCK_DEFINE" introspectable="0"> + <doc xml:space="preserve">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; + } +]|</doc> + <parameters> + <parameter name="name"> + <doc xml:space="preserve">the name of the lock</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="LOCK_DEFINE_STATIC" c:identifier="G_LOCK_DEFINE_STATIC" introspectable="0"> + <doc xml:space="preserve">This works like #G_LOCK_DEFINE, but it creates a static object.</doc> + <parameters> + <parameter name="name"> + <doc xml:space="preserve">the name of the lock</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="LOCK_EXTERN" c:identifier="G_LOCK_EXTERN" introspectable="0"> + <doc xml:space="preserve">This declares a lock, that is defined with #G_LOCK_DEFINE in another +module.</doc> + <parameters> + <parameter name="name"> + <doc xml:space="preserve">the name of the lock</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="LOCK_NAME" c:identifier="G_LOCK_NAME" introspectable="0"> + <parameters> + <parameter name="name"> + </parameter> + </parameters> + </function-macro> + <constant name="LOG_2_BASE_10" value="0.301030" c:type="G_LOG_2_BASE_10"> + <doc xml:space="preserve">Multiplying the base 2 exponent by this number yields the base 10 exponent.</doc> + <type name="gdouble" c:type="gdouble"/> + </constant> + <constant name="LOG_DOMAIN" value="0" c:type="G_LOG_DOMAIN"> + <doc xml:space="preserve">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.</doc> + <type name="gchar" c:type="gchar"/> + </constant> + <constant name="LOG_FATAL_MASK" value="5" c:type="G_LOG_FATAL_MASK"> + <doc xml:space="preserve">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].</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="LOG_LEVEL_USER_SHIFT" value="8" c:type="G_LOG_LEVEL_USER_SHIFT"> + <doc xml:space="preserve">Log levels below 1<<G_LOG_LEVEL_USER_SHIFT are used by GLib. +Higher bits can be used for user-defined log levels.</doc> + <type name="gint" c:type="gint"/> + </constant> + <record name="List" c:type="GList"> + <doc xml:space="preserve">The #GList struct is used for each element in a doubly-linked list.</doc> + <field name="data" writable="1"> + <doc xml:space="preserve">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]</doc> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="next" writable="1"> + <doc xml:space="preserve">contains the link to the next element in the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </field> + <field name="prev" writable="1"> + <doc xml:space="preserve">contains the link to the previous element in the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </field> + <function name="alloc" c:identifier="g_list_alloc" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">a pointer to the newly-allocated #GList element</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + </function> + <function name="append" c:identifier="g_list_append" introspectable="0"> + <doc xml:space="preserve">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)); +]|</doc> + <return-value> + <doc xml:space="preserve">either @list or the new start of the #GList if @list was %NULL</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new element</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="concat" c:identifier="g_list_concat" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <return-value> + <doc xml:space="preserve">the start of the new #GList, which equals @list1 if not %NULL</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list1" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="list2" transfer-ownership="none"> + <doc xml:space="preserve">the #GList to add to the end of the first #GList, + this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="copy" c:identifier="g_list_copy" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the start of the new list that holds the same data as @list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="copy_deep" c:identifier="g_list_copy_deep" version="2.34" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <return-value> + <doc xml:space="preserve">the start of the new list that holds a full copy of @list, + use g_list_free_full() to free it</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">a copy function used to copy every element in the list</doc> + <type name="CopyFunc" c:type="GCopyFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to the copy function @func, or %NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="delete_link" c:identifier="g_list_delete_link" introspectable="0"> + <doc xml:space="preserve">Removes the node link_ from the list and frees it. +Compare this to g_list_remove_link() which removes the node +without freeing it.</doc> + <return-value> + <doc xml:space="preserve">the (possibly changed) start of the #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="link_" transfer-ownership="none"> + <doc xml:space="preserve">node to delete from @list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="find" c:identifier="g_list_find" introspectable="0"> + <doc xml:space="preserve">Finds the element in a #GList which contains the given data.</doc> + <return-value> + <doc xml:space="preserve">the found #GList element, or %NULL if it is not found</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the element data to find</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="find_custom" c:identifier="g_list_find_custom" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the found #GList element, or %NULL if it is not found</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to the function</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="func" transfer-ownership="none"> + <doc xml:space="preserve">the function to call for each element. + It should return 0 when the desired element is found</doc> + <type name="CompareFunc" c:type="GCompareFunc"/> + </parameter> + </parameters> + </function> + <function name="first" c:identifier="g_list_first" introspectable="0"> + <doc xml:space="preserve">Gets the first element in a #GList.</doc> + <return-value> + <doc xml:space="preserve">the first element in the #GList, + or %NULL if the #GList has no elements</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">any #GList element</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="foreach" c:identifier="g_list_foreach" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function to call with each element's data</doc> + <type name="Func" c:type="GFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to the function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="free" c:identifier="g_list_free" introspectable="0"> + <doc xml:space="preserve">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)); +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">the first link of a #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="free_1" c:identifier="g_list_free_1" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList element</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="free_full" c:identifier="g_list_free_full" version="2.28" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">the first link of a #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="free_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">the function to be called to free each element's data</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="index" c:identifier="g_list_index" introspectable="0"> + <doc xml:space="preserve">Gets the position of the element containing +the given data (starting from 0).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the index of the element containing the data, + or -1 if the data is not found</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to find</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="insert" c:identifier="g_list_insert" introspectable="0"> + <doc xml:space="preserve">Inserts a new element into the list at the given position.</doc> + <return-value> + <doc xml:space="preserve">the (possibly changed) start of the #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new element</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="insert_before" c:identifier="g_list_insert_before" introspectable="0"> + <doc xml:space="preserve">Inserts a new element into the list before the given position.</doc> + <return-value> + <doc xml:space="preserve">the (possibly changed) start of the #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="sibling" transfer-ownership="none"> + <doc xml:space="preserve">the list element before which the new element + is inserted or %NULL to insert at the end of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new element</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="insert_before_link" c:identifier="g_list_insert_before_link" version="2.62" introspectable="0"> + <doc xml:space="preserve">Inserts @link_ into the list before the given position.</doc> + <return-value> + <doc xml:space="preserve">the (possibly changed) start of the #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="sibling" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the list element before which the new element + is inserted or %NULL to insert at the end of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="link_" transfer-ownership="none"> + <doc xml:space="preserve">the list element to be added, which must not be part of + any other list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="insert_sorted" c:identifier="g_list_insert_sorted" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value> + <doc xml:space="preserve">the (possibly changed) start of the #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GList, this must point to the top of the + already sorted list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new element</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="func" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="CompareFunc" c:type="GCompareFunc"/> + </parameter> + </parameters> + </function> + <function name="insert_sorted_with_data" c:identifier="g_list_insert_sorted_with_data" version="2.10" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value> + <doc xml:space="preserve">the (possibly changed) start of the #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GList, this must point to the top of the + already sorted list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new element</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="func" transfer-ownership="none" closure="3"> + <doc xml:space="preserve">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.</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to comparison function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="last" c:identifier="g_list_last" introspectable="0"> + <doc xml:space="preserve">Gets the last element in a #GList.</doc> + <return-value> + <doc xml:space="preserve">the last element in the #GList, + or %NULL if the #GList has no elements</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">any #GList element</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="length" c:identifier="g_list_length" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of elements in the #GList</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="nth" c:identifier="g_list_nth" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the element, or %NULL if the position is off + the end of the #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">the position of the element, counting from 0</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="nth_data" c:identifier="g_list_nth_data" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the element's data, or %NULL if the position + is off the end of the #GList</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">the position of the element</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="nth_prev" c:identifier="g_list_nth_prev" introspectable="0"> + <doc xml:space="preserve">Gets the element @n places before @list.</doc> + <return-value> + <doc xml:space="preserve">the element, or %NULL if the position is + off the end of the #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">the position of the element, counting from 0</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="position" c:identifier="g_list_position" introspectable="0"> + <doc xml:space="preserve">Gets the position of the given element +in the #GList (starting from 0).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the position of the element in the #GList, + or -1 if the element is not found</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="llink" transfer-ownership="none"> + <doc xml:space="preserve">an element in the #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="prepend" c:identifier="g_list_prepend" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">a pointer to the newly prepended element, which is the new + start of the #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new element</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="remove" c:identifier="g_list_remove" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the (possibly changed) start of the #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data of the element to remove</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="remove_all" c:identifier="g_list_remove_all" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the (possibly changed) start of the #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to remove</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="remove_link" c:identifier="g_list_remove_link" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <return-value> + <doc xml:space="preserve">the (possibly changed) start of the #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="llink" transfer-ownership="none"> + <doc xml:space="preserve">an element in the #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="reverse" c:identifier="g_list_reverse" introspectable="0"> + <doc xml:space="preserve">Reverses a #GList. +It simply switches the next and prev pointers of each element.</doc> + <return-value> + <doc xml:space="preserve">the start of the reversed #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="sort" c:identifier="g_list_sort" introspectable="0"> + <doc xml:space="preserve">Sorts a #GList using the given comparison function. The algorithm +used is a stable sort.</doc> + <return-value> + <doc xml:space="preserve">the (possibly changed) start of the #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="compare_func" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="CompareFunc" c:type="GCompareFunc"/> + </parameter> + </parameters> + </function> + <function name="sort_with_data" c:identifier="g_list_sort_with_data" introspectable="0"> + <doc xml:space="preserve">Like g_list_sort(), but the comparison function accepts +a user data argument.</doc> + <return-value> + <doc xml:space="preserve">the (possibly changed) start of the #GList</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GList, this must point to the top of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="compare_func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">comparison function</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to comparison function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + </record> + <record name="LogField" c:type="GLogField" version="2.50"> + <doc xml:space="preserve">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.</doc> + <field name="key" writable="1"> + <doc xml:space="preserve">field name (UTF-8 string)</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="value" writable="1"> + <doc xml:space="preserve">field value (arbitrary bytes)</doc> + <type name="gpointer" c:type="gconstpointer"/> + </field> + <field name="length" writable="1"> + <doc xml:space="preserve">length of @value, in bytes, or -1 if it is nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </field> + </record> + <callback name="LogFunc" c:type="GLogFunc"> + <doc xml:space="preserve">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].</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="log_domain" transfer-ownership="none"> + <doc xml:space="preserve">the log domain of the message</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="log_level" transfer-ownership="none"> + <doc xml:space="preserve">the log level of the message (including the + fatal and recursion flags)</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">the message to process</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">user data, set in g_log_set_handler()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <bitfield name="LogLevelFlags" c:type="GLogLevelFlags"> + <doc xml:space="preserve">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().</doc> + <member name="flag_recursion" value="1" c:identifier="G_LOG_FLAG_RECURSION"> + <doc xml:space="preserve">internal flag</doc> + </member> + <member name="flag_fatal" value="2" c:identifier="G_LOG_FLAG_FATAL"> + <doc xml:space="preserve">internal flag</doc> + </member> + <member name="level_error" value="4" c:identifier="G_LOG_LEVEL_ERROR"> + <doc xml:space="preserve">log level for errors, see g_error(). + This level is also used for messages produced by g_assert().</doc> + </member> + <member name="level_critical" value="8" c:identifier="G_LOG_LEVEL_CRITICAL"> + <doc xml:space="preserve">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().</doc> + </member> + <member name="level_warning" value="16" c:identifier="G_LOG_LEVEL_WARNING"> + <doc xml:space="preserve">log level for warnings, see g_warning()</doc> + </member> + <member name="level_message" value="32" c:identifier="G_LOG_LEVEL_MESSAGE"> + <doc xml:space="preserve">log level for messages, see g_message()</doc> + </member> + <member name="level_info" value="64" c:identifier="G_LOG_LEVEL_INFO"> + <doc xml:space="preserve">log level for informational messages, see g_info()</doc> + </member> + <member name="level_debug" value="128" c:identifier="G_LOG_LEVEL_DEBUG"> + <doc xml:space="preserve">log level for debug messages, see g_debug()</doc> + </member> + <member name="level_mask" value="-4" c:identifier="G_LOG_LEVEL_MASK"> + <doc xml:space="preserve">a mask including all log levels</doc> + </member> + </bitfield> + <callback name="LogWriterFunc" c:type="GLogWriterFunc" version="2.50"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%G_LOG_WRITER_HANDLED if the log entry was handled successfully; + %G_LOG_WRITER_UNHANDLED otherwise</doc> + <type name="LogWriterOutput" c:type="GLogWriterOutput"/> + </return-value> + <parameters> + <parameter name="log_level" transfer-ownership="none"> + <doc xml:space="preserve">log level of the message</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="fields" transfer-ownership="none"> + <doc xml:space="preserve">fields forming the message</doc> + <array length="2" zero-terminated="0" c:type="const GLogField*"> + <type name="LogField" c:type="GLogField"/> + </array> + </parameter> + <parameter name="n_fields" transfer-ownership="none"> + <doc xml:space="preserve">number of @fields</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">user data passed to g_log_set_writer_func()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <enumeration name="LogWriterOutput" version="2.50" c:type="GLogWriterOutput"> + <doc xml:space="preserve">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.</doc> + <member name="handled" value="1" c:identifier="G_LOG_WRITER_HANDLED"> + <doc xml:space="preserve">Log writer has handled the log entry.</doc> + </member> + <member name="unhandled" value="0" c:identifier="G_LOG_WRITER_UNHANDLED"> + <doc xml:space="preserve">Log writer could not handle the log entry.</doc> + </member> + </enumeration> + <constant name="MAJOR_VERSION" value="2" c:type="GLIB_MAJOR_VERSION"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="MAXINT16" value="32767" c:type="G_MAXINT16" version="2.4"> + <doc xml:space="preserve">The maximum value which can be held in a #gint16.</doc> + <type name="gint16" c:type="gint16"/> + </constant> + <constant name="MAXINT32" value="2147483647" c:type="G_MAXINT32" version="2.4"> + <doc xml:space="preserve">The maximum value which can be held in a #gint32.</doc> + <type name="gint32" c:type="gint32"/> + </constant> + <constant name="MAXINT64" value="9223372036854775807" c:type="G_MAXINT64"> + <doc xml:space="preserve">The maximum value which can be held in a #gint64.</doc> + <type name="gint64" c:type="gint64"/> + </constant> + <constant name="MAXINT8" value="127" c:type="G_MAXINT8" version="2.4"> + <doc xml:space="preserve">The maximum value which can be held in a #gint8.</doc> + <type name="gint8" c:type="gint8"/> + </constant> + <constant name="MAXUINT16" value="65535" c:type="G_MAXUINT16" version="2.4"> + <doc xml:space="preserve">The maximum value which can be held in a #guint16.</doc> + <type name="guint16" c:type="guint16"/> + </constant> + <constant name="MAXUINT32" value="4294967295" c:type="G_MAXUINT32" version="2.4"> + <doc xml:space="preserve">The maximum value which can be held in a #guint32.</doc> + <type name="guint32" c:type="guint32"/> + </constant> + <constant name="MAXUINT64" value="18446744073709551615" c:type="G_MAXUINT64"> + <doc xml:space="preserve">The maximum value which can be held in a #guint64.</doc> + <type name="guint64" c:type="guint64"/> + </constant> + <constant name="MAXUINT8" value="255" c:type="G_MAXUINT8" version="2.4"> + <doc xml:space="preserve">The maximum value which can be held in a #guint8.</doc> + <type name="guint8" c:type="guint8"/> + </constant> + <constant name="MICRO_VERSION" value="7" c:type="GLIB_MICRO_VERSION"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="MININT16" value="-32768" c:type="G_MININT16" version="2.4"> + <doc xml:space="preserve">The minimum value which can be held in a #gint16.</doc> + <type name="gint16" c:type="gint16"/> + </constant> + <constant name="MININT32" value="-2147483648" c:type="G_MININT32" version="2.4"> + <doc xml:space="preserve">The minimum value which can be held in a #gint32.</doc> + <type name="gint32" c:type="gint32"/> + </constant> + <constant name="MININT64" value="-9223372036854775808" c:type="G_MININT64"> + <doc xml:space="preserve">The minimum value which can be held in a #gint64.</doc> + <type name="gint64" c:type="gint64"/> + </constant> + <constant name="MININT8" value="-128" c:type="G_MININT8" version="2.4"> + <doc xml:space="preserve">The minimum value which can be held in a #gint8.</doc> + <type name="gint8" c:type="gint8"/> + </constant> + <constant name="MINOR_VERSION" value="66" c:type="GLIB_MINOR_VERSION"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="MODULE_SUFFIX" value="so" c:type="G_MODULE_SUFFIX"> + <type name="utf8" c:type="gchar*"/> + </constant> + <record name="MainContext" c:type="GMainContext" glib:type-name="GMainContext" glib:get-type="g_main_context_get_type" c:symbol-prefix="main_context"> + <doc xml:space="preserve">The `GMainContext` struct is an opaque data +type representing a set of sources to be handled in a main loop.</doc> + <constructor name="new" c:identifier="g_main_context_new"> + <doc xml:space="preserve">Creates a new #GMainContext structure.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new #GMainContext</doc> + <type name="MainContext" c:type="GMainContext*"/> + </return-value> + </constructor> + <method name="acquire" c:identifier="g_main_context_acquire"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation succeeded, and + this thread is now the owner of @context.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainContext</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="add_poll" c:identifier="g_main_context_add_poll"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMainContext (or %NULL for the default context)</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollFD structure holding information about a file + descriptor to watch.</doc> + <type name="PollFD" c:type="GPollFD*"/> + </parameter> + <parameter name="priority" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="check" c:identifier="g_main_context_check"> + <doc xml:space="preserve">Passes the results of polling back to the main loop. You should be +careful to pass @fds and its length @n_fds as received from +g_main_context_query(), as this functions relies on assumptions +on how @fds is filled. + +You must have successfully acquired the context with +g_main_context_acquire() before you may call this function.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if some sources are ready to be dispatched.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainContext</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + <parameter name="max_priority" transfer-ownership="none"> + <doc xml:space="preserve">the maximum numerical priority of sources to check</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="fds" transfer-ownership="none"> + <doc xml:space="preserve">array of #GPollFD's that was passed to + the last call to g_main_context_query()</doc> + <array length="2" zero-terminated="0" c:type="GPollFD*"> + <type name="PollFD" c:type="GPollFD"/> + </array> + </parameter> + <parameter name="n_fds" transfer-ownership="none"> + <doc xml:space="preserve">return value of g_main_context_query()</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="dispatch" c:identifier="g_main_context_dispatch"> + <doc xml:space="preserve">Dispatches all pending sources. + +You must have successfully acquired the context with +g_main_context_acquire() before you may call this function.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainContext</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="find_source_by_funcs_user_data" c:identifier="g_main_context_find_source_by_funcs_user_data"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the source, if one was found, otherwise %NULL</doc> + <type name="Source" c:type="GSource*"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMainContext (if %NULL, the default context will be used).</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + <parameter name="funcs" transfer-ownership="none"> + <doc xml:space="preserve">the @source_funcs passed to g_source_new().</doc> + <type name="SourceFuncs" c:type="GSourceFuncs*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the user data from the callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="find_source_by_id" c:identifier="g_main_context_find_source_by_id"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GSource</doc> + <type name="Source" c:type="GSource*"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMainContext (if %NULL, the default context will be used)</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + <parameter name="source_id" transfer-ownership="none"> + <doc xml:space="preserve">the source ID, as returned by g_source_get_id().</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="find_source_by_user_data" c:identifier="g_main_context_find_source_by_user_data"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the source, if one was found, otherwise %NULL</doc> + <type name="Source" c:type="GSource*"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainContext</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the user_data for the callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="get_poll_func" c:identifier="g_main_context_get_poll_func" introspectable="0"> + <doc xml:space="preserve">Gets the poll function set by g_main_context_set_poll_func().</doc> + <return-value> + <doc xml:space="preserve">the poll function</doc> + <type name="PollFunc" c:type="GPollFunc"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainContext</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="invoke" c:identifier="g_main_context_invoke" version="2.28" introspectable="0"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMainContext, or %NULL</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + <parameter name="function" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">function to call</doc> + <type name="SourceFunc" c:type="GSourceFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="invoke_full" c:identifier="g_main_context_invoke_full" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMainContext, or %NULL</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + <parameter name="priority" transfer-ownership="none"> + <doc xml:space="preserve">the priority at which to run @function</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="function" transfer-ownership="none" scope="notified" closure="2" destroy="3"> + <doc xml:space="preserve">function to call</doc> + <type name="SourceFunc" c:type="GSourceFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a function to call when @data is no longer in use, or %NULL.</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="is_owner" c:identifier="g_main_context_is_owner" version="2.10"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if current thread is owner of @context.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainContext</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="iteration" c:identifier="g_main_context_iteration"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if events were dispatched.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMainContext (if %NULL, the default context will be used)</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + <parameter name="may_block" transfer-ownership="none"> + <doc xml:space="preserve">whether the call may block.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="pending" c:identifier="g_main_context_pending"> + <doc xml:space="preserve">Checks if any sources have pending events for the given context.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if events are pending.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMainContext (if %NULL, the default context will be used)</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="pop_thread_default" c:identifier="g_main_context_pop_thread_default" version="2.22"> + <doc xml:space="preserve">Pops @context off the thread-default context stack (verifying that +it was on the top of the stack).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMainContext object, or %NULL</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="prepare" c:identifier="g_main_context_prepare"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if some source is ready to be dispatched + prior to polling.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainContext</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + <parameter name="priority" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store priority of highest priority + source already ready.</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </method> + <method name="push_thread_default" c:identifier="g_main_context_push_thread_default" version="2.22"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMainContext, or %NULL for the global default context</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="query" c:identifier="g_main_context_query"> + <doc xml:space="preserve">Determines information necessary to poll this main loop. You should +be careful to pass the resulting @fds array and its length @n_fds +as is when calling g_main_context_check(), as this function relies +on assumptions made when the array is filled. + +You must have successfully acquired the context with +g_main_context_acquire() before you may call this function.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainContext</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + <parameter name="max_priority" transfer-ownership="none"> + <doc xml:space="preserve">maximum priority source to check</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="timeout_" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">location to store timeout to be used in polling</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="fds" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve">location to + store #GPollFD records that need to be polled.</doc> + <array length="3" zero-terminated="0" c:type="GPollFD*"> + <type name="PollFD" c:type="GPollFD"/> + </array> + </parameter> + <parameter name="n_fds" transfer-ownership="none"> + <doc xml:space="preserve">length of @fds.</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_main_context_ref"> + <doc xml:space="preserve">Increases the reference count on a #GMainContext object by one.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the @context that was passed in (since 2.6)</doc> + <type name="MainContext" c:type="GMainContext*"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainContext</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="release" c:identifier="g_main_context_release"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainContext</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="remove_poll" c:identifier="g_main_context_remove_poll"> + <doc xml:space="preserve">Removes file descriptor from the set of file descriptors to be +polled for a particular context.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainContext</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollFD descriptor previously added with g_main_context_add_poll()</doc> + <type name="PollFD" c:type="GPollFD*"/> + </parameter> + </parameters> + </method> + <method name="set_poll_func" c:identifier="g_main_context_set_poll_func" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainContext</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + <parameter name="func" transfer-ownership="none"> + <doc xml:space="preserve">the function to call to poll all file descriptors</doc> + <type name="PollFunc" c:type="GPollFunc"/> + </parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_main_context_unref"> + <doc xml:space="preserve">Decreases the reference count on a #GMainContext object by one. If +the result is zero, free the context and free all associated memory.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainContext</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="wait" c:identifier="g_main_context_wait" deprecated="1" deprecated-version="2.58"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_main_context_is_owner() and separate locking instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation succeeded, and + this thread is now the owner of @context.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainContext</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + <parameter name="cond" transfer-ownership="none"> + <doc xml:space="preserve">a condition variable</doc> + <type name="Cond" c:type="GCond*"/> + </parameter> + <parameter name="mutex" transfer-ownership="none"> + <doc xml:space="preserve">a mutex, currently held</doc> + <type name="Mutex" c:type="GMutex*"/> + </parameter> + </parameters> + </method> + <method name="wakeup" c:identifier="g_main_context_wakeup"> + <doc xml:space="preserve">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 gint tasks_remaining = NUM_TASKS; // (atomic) + ... + + 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); +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainContext</doc> + <type name="MainContext" c:type="GMainContext*"/> + </instance-parameter> + </parameters> + </method> + <function name="default" c:identifier="g_main_context_default"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the global default main context.</doc> + <type name="MainContext" c:type="GMainContext*"/> + </return-value> + </function> + <function name="get_thread_default" c:identifier="g_main_context_get_thread_default" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the thread-default #GMainContext, or +%NULL if the thread-default context is the global default context.</doc> + <type name="MainContext" c:type="GMainContext*"/> + </return-value> + </function> + <function name="ref_thread_default" c:identifier="g_main_context_ref_thread_default" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the thread-default #GMainContext. Unref + with g_main_context_unref() when you are done with it.</doc> + <type name="MainContext" c:type="GMainContext*"/> + </return-value> + </function> + </record> + <record name="MainLoop" c:type="GMainLoop" glib:type-name="GMainLoop" glib:get-type="g_main_loop_get_type" c:symbol-prefix="main_loop"> + <doc xml:space="preserve">The `GMainLoop` struct is an opaque data type +representing the main event loop of a GLib or GTK+ application.</doc> + <constructor name="new" c:identifier="g_main_loop_new"> + <doc xml:space="preserve">Creates a new #GMainLoop structure.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GMainLoop.</doc> + <type name="MainLoop" c:type="GMainLoop*"/> + </return-value> + <parameters> + <parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMainContext (if %NULL, the default context will be used).</doc> + <type name="MainContext" c:type="GMainContext*"/> + </parameter> + <parameter name="is_running" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </constructor> + <method name="get_context" c:identifier="g_main_loop_get_context"> + <doc xml:space="preserve">Returns the #GMainContext of @loop.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GMainContext of @loop</doc> + <type name="MainContext" c:type="GMainContext*"/> + </return-value> + <parameters> + <instance-parameter name="loop" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainLoop.</doc> + <type name="MainLoop" c:type="GMainLoop*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_running" c:identifier="g_main_loop_is_running"> + <doc xml:space="preserve">Checks to see if the main loop is currently being run via g_main_loop_run().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mainloop is currently being run.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="loop" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainLoop.</doc> + <type name="MainLoop" c:type="GMainLoop*"/> + </instance-parameter> + </parameters> + </method> + <method name="quit" c:identifier="g_main_loop_quit"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="loop" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainLoop</doc> + <type name="MainLoop" c:type="GMainLoop*"/> + </instance-parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_main_loop_ref"> + <doc xml:space="preserve">Increases the reference count on a #GMainLoop object by one.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">@loop</doc> + <type name="MainLoop" c:type="GMainLoop*"/> + </return-value> + <parameters> + <instance-parameter name="loop" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainLoop</doc> + <type name="MainLoop" c:type="GMainLoop*"/> + </instance-parameter> + </parameters> + </method> + <method name="run" c:identifier="g_main_loop_run"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="loop" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainLoop</doc> + <type name="MainLoop" c:type="GMainLoop*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_main_loop_unref"> + <doc xml:space="preserve">Decreases the reference count on a #GMainLoop object by one. If +the result is zero, free the loop and free all associated memory.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="loop" transfer-ownership="none"> + <doc xml:space="preserve">a #GMainLoop</doc> + <type name="MainLoop" c:type="GMainLoop*"/> + </instance-parameter> + </parameters> + </method> + </record> + <record name="MappedFile" c:type="GMappedFile" glib:type-name="GMappedFile" glib:get-type="g_mapped_file_get_type" c:symbol-prefix="mapped_file"> + <doc xml:space="preserve">The #GMappedFile represents a file mapping created with +g_mapped_file_new(). It has only private members and should +not be accessed directly.</doc> + <constructor name="new" c:identifier="g_mapped_file_new" version="2.8" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated #GMappedFile which must be unref'd + with g_mapped_file_unref(), or %NULL if the mapping failed.</doc> + <type name="MappedFile" c:type="GMappedFile*"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">The path of the file to load, in the GLib + filename encoding</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="writable" transfer-ownership="none"> + <doc xml:space="preserve">whether the mapping should be writable</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_fd" c:identifier="g_mapped_file_new_from_fd" version="2.32" throws="1"> + <doc xml:space="preserve">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()).</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated #GMappedFile which must be unref'd + with g_mapped_file_unref(), or %NULL if the mapping failed.</doc> + <type name="MappedFile" c:type="GMappedFile*"/> + </return-value> + <parameters> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">The file descriptor of the file to load</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="writable" transfer-ownership="none"> + <doc xml:space="preserve">whether the mapping should be writable</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </constructor> + <method name="free" c:identifier="g_mapped_file_free" version="2.8" deprecated="1" deprecated-version="2.22"> + <doc xml:space="preserve">This call existed before #GMappedFile had refcounting and is currently +exactly the same as g_mapped_file_unref().</doc> + <doc-deprecated xml:space="preserve">Use g_mapped_file_unref() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GMappedFile</doc> + <type name="MappedFile" c:type="GMappedFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_bytes" c:identifier="g_mapped_file_get_bytes" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A newly allocated #GBytes referencing data + from @file</doc> + <type name="Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GMappedFile</doc> + <type name="MappedFile" c:type="GMappedFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_contents" c:identifier="g_mapped_file_get_contents" version="2.8"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the contents of @file, or %NULL.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GMappedFile</doc> + <type name="MappedFile" c:type="GMappedFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_length" c:identifier="g_mapped_file_get_length" version="2.8"> + <doc xml:space="preserve">Returns the length of the contents of a #GMappedFile.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the length of the contents of @file.</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GMappedFile</doc> + <type name="MappedFile" c:type="GMappedFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_mapped_file_ref" version="2.22"> + <doc xml:space="preserve">Increments the reference count of @file by one. It is safe to call +this function from any thread.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the passed in #GMappedFile.</doc> + <type name="MappedFile" c:type="GMappedFile*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GMappedFile</doc> + <type name="MappedFile" c:type="GMappedFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_mapped_file_unref"> + <doc xml:space="preserve">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</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GMappedFile</doc> + <type name="MappedFile" c:type="GMappedFile*"/> + </instance-parameter> + </parameters> + </method> + </record> + <bitfield name="MarkupCollectType" c:type="GMarkupCollectType"> + <doc xml:space="preserve">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.</doc> + <member name="invalid" value="0" c:identifier="G_MARKUP_COLLECT_INVALID"> + <doc xml:space="preserve">used to terminate the list of attributes + to collect</doc> + </member> + <member name="string" value="1" c:identifier="G_MARKUP_COLLECT_STRING"> + <doc xml:space="preserve">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</doc> + </member> + <member name="strdup" value="2" c:identifier="G_MARKUP_COLLECT_STRDUP"> + <doc xml:space="preserve">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()</doc> + </member> + <member name="boolean" value="3" c:identifier="G_MARKUP_COLLECT_BOOLEAN"> + <doc xml:space="preserve">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"</doc> + </member> + <member name="tristate" value="4" c:identifier="G_MARKUP_COLLECT_TRISTATE"> + <doc xml:space="preserve">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</doc> + </member> + <member name="optional" value="65536" c:identifier="G_MARKUP_COLLECT_OPTIONAL"> + <doc xml:space="preserve">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</doc> + </member> + </bitfield> + <enumeration name="MarkupError" c:type="GMarkupError" glib:error-domain="g-markup-error-quark"> + <doc xml:space="preserve">Error codes returned by markup parsing.</doc> + <member name="bad_utf8" value="0" c:identifier="G_MARKUP_ERROR_BAD_UTF8"> + <doc xml:space="preserve">text being parsed was not valid UTF-8</doc> + </member> + <member name="empty" value="1" c:identifier="G_MARKUP_ERROR_EMPTY"> + <doc xml:space="preserve">document contained nothing, or only whitespace</doc> + </member> + <member name="parse" value="2" c:identifier="G_MARKUP_ERROR_PARSE"> + <doc xml:space="preserve">document was ill-formed</doc> + </member> + <member name="unknown_element" value="3" c:identifier="G_MARKUP_ERROR_UNKNOWN_ELEMENT"> + <doc xml:space="preserve">error should be set by #GMarkupParser + functions; element wasn't known</doc> + </member> + <member name="unknown_attribute" value="4" c:identifier="G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE"> + <doc xml:space="preserve">error should be set by #GMarkupParser + functions; attribute wasn't known</doc> + </member> + <member name="invalid_content" value="5" c:identifier="G_MARKUP_ERROR_INVALID_CONTENT"> + <doc xml:space="preserve">error should be set by #GMarkupParser + functions; content was invalid</doc> + </member> + <member name="missing_attribute" value="6" c:identifier="G_MARKUP_ERROR_MISSING_ATTRIBUTE"> + <doc xml:space="preserve">error should be set by #GMarkupParser + functions; a required attribute was missing</doc> + </member> + </enumeration> + <record name="MarkupParseContext" c:type="GMarkupParseContext" glib:type-name="GMarkupParseContext" glib:get-type="g_markup_parse_context_get_type" c:symbol-prefix="markup_parse_context"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_markup_parse_context_new"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GMarkupParseContext</doc> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </return-value> + <parameters> + <parameter name="parser" transfer-ownership="none"> + <doc xml:space="preserve">a #GMarkupParser</doc> + <type name="MarkupParser" c:type="const GMarkupParser*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">one or more #GMarkupParseFlags</doc> + <type name="MarkupParseFlags" c:type="GMarkupParseFlags"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to #GMarkupParser functions</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="user_data_dnotify" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">user data destroy notifier called when + the parse context is freed</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </constructor> + <method name="end_parse" c:identifier="g_markup_parse_context_end_parse" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if an error was set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMarkupParseContext</doc> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="free" c:identifier="g_markup_parse_context_free"> + <doc xml:space="preserve">Frees a #GMarkupParseContext. + +This function can't be called from inside one of the +#GMarkupParser functions or while a subparser is pushed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMarkupParseContext</doc> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_element" c:identifier="g_markup_parse_context_get_element" version="2.2"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the name of the currently open element, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMarkupParseContext</doc> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_element_stack" c:identifier="g_markup_parse_context_get_element_stack" version="2.16" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the element stack, which must not be modified</doc> + <type name="GLib.SList" c:type="const GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMarkupParseContext</doc> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_position" c:identifier="g_markup_parse_context_get_position"> + <doc xml:space="preserve">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."</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMarkupParseContext</doc> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </instance-parameter> + <parameter name="line_number" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for a line number, or %NULL</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="char_number" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for a char-on-line number, or %NULL</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </method> + <method name="get_user_data" c:identifier="g_markup_parse_context_get_user_data" version="2.18"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the provided user_data. The returned data belongs to + the markup context and will be freed when + g_markup_parse_context_free() is called.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMarkupParseContext</doc> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="parse" c:identifier="g_markup_parse_context_parse" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%FALSE if an error occurred, %TRUE on success</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMarkupParseContext</doc> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </instance-parameter> + <parameter name="text" transfer-ownership="none"> + <doc xml:space="preserve">chunk of text to parse</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="text_len" transfer-ownership="none"> + <doc xml:space="preserve">length of @text in bytes</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </method> + <method name="pop" c:identifier="g_markup_parse_context_pop" version="2.18"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the user data passed to g_markup_parse_context_push()</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMarkupParseContext</doc> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="push" c:identifier="g_markup_parse_context_push" version="2.18"> + <doc xml:space="preserve">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... +} +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMarkupParseContext</doc> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </instance-parameter> + <parameter name="parser" transfer-ownership="none"> + <doc xml:space="preserve">a #GMarkupParser</doc> + <type name="MarkupParser" c:type="const GMarkupParser*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to #GMarkupParser functions</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_markup_parse_context_ref" version="2.36"> + <doc xml:space="preserve">Increases the reference count of @context.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the same @context</doc> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMarkupParseContext</doc> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_markup_parse_context_unref" version="2.36"> + <doc xml:space="preserve">Decreases the reference count of @context. When its reference count +drops to 0, it is freed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GMarkupParseContext</doc> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </instance-parameter> + </parameters> + </method> + </record> + <bitfield name="MarkupParseFlags" c:type="GMarkupParseFlags"> + <doc xml:space="preserve">Flags that affect the behaviour of the parser.</doc> + <member name="do_not_use_this_unsupported_flag" value="1" c:identifier="G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG"> + <doc xml:space="preserve">flag you should not use</doc> + </member> + <member name="treat_cdata_as_text" value="2" c:identifier="G_MARKUP_TREAT_CDATA_AS_TEXT"> + <doc xml:space="preserve">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</doc> + </member> + <member name="prefix_error_position" value="4" c:identifier="G_MARKUP_PREFIX_ERROR_POSITION"> + <doc xml:space="preserve">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</doc> + </member> + <member name="ignore_qualified" value="8" c:identifier="G_MARKUP_IGNORE_QUALIFIED"> + <doc xml:space="preserve">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.</doc> + </member> + </bitfield> + <record name="MarkupParser" c:type="GMarkupParser"> + <doc xml:space="preserve">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.</doc> + <field name="start_element"> + <callback name="start_element" throws="1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="context" transfer-ownership="none"> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </parameter> + <parameter name="element_name" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="attribute_names" transfer-ownership="none"> + <type name="utf8" c:type="const gchar**"/> + </parameter> + <parameter name="attribute_values" transfer-ownership="none"> + <type name="utf8" c:type="const gchar**"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="end_element"> + <callback name="end_element" throws="1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="context" transfer-ownership="none"> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </parameter> + <parameter name="element_name" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="text"> + <callback name="text" throws="1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="context" transfer-ownership="none"> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </parameter> + <parameter name="text" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="text_len" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="passthrough"> + <callback name="passthrough" throws="1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="context" transfer-ownership="none"> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </parameter> + <parameter name="passthrough_text" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="text_len" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="error"> + <callback name="error"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="context" transfer-ownership="none"> + <type name="MarkupParseContext" c:type="GMarkupParseContext*"/> + </parameter> + <parameter name="error" transfer-ownership="none"> + <type name="Error" c:type="GError*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <record name="MatchInfo" c:type="GMatchInfo" glib:type-name="GMatchInfo" glib:get-type="g_match_info_get_type" c:symbol-prefix="match_info"> + <doc xml:space="preserve">A GMatchInfo is an opaque struct used to return information about +matches.</doc> + <method name="expand_references" c:identifier="g_match_info_expand_references" version="2.14" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the expanded string, or %NULL if an error occurred</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="match_info" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMatchInfo or %NULL</doc> + <type name="MatchInfo" c:type="const GMatchInfo*"/> + </instance-parameter> + <parameter name="string_to_expand" transfer-ownership="none"> + <doc xml:space="preserve">the string to expand</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="fetch" c:identifier="g_match_info_fetch" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">The matched substring, or %NULL if an error + occurred. You have to free the string yourself</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="match_info" transfer-ownership="none"> + <doc xml:space="preserve">#GMatchInfo structure</doc> + <type name="MatchInfo" c:type="const GMatchInfo*"/> + </instance-parameter> + <parameter name="match_num" transfer-ownership="none"> + <doc xml:space="preserve">number of the sub expression</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="fetch_all" c:identifier="g_match_info_fetch_all" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated array of gchar * + pointers. It must be freed using g_strfreev(). If the previous + match failed %NULL is returned</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="match_info" transfer-ownership="none"> + <doc xml:space="preserve">a #GMatchInfo structure</doc> + <type name="MatchInfo" c:type="const GMatchInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="fetch_named" c:identifier="g_match_info_fetch_named" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">The matched substring, or %NULL if an error + occurred. You have to free the string yourself</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="match_info" transfer-ownership="none"> + <doc xml:space="preserve">#GMatchInfo structure</doc> + <type name="MatchInfo" c:type="const GMatchInfo*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">name of the subexpression</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="fetch_named_pos" c:identifier="g_match_info_fetch_named_pos" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the position was fetched, %FALSE otherwise. + If the position cannot be fetched, @start_pos and @end_pos + are left unchanged.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="match_info" transfer-ownership="none"> + <doc xml:space="preserve">#GMatchInfo structure</doc> + <type name="MatchInfo" c:type="const GMatchInfo*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">name of the subexpression</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="start_pos" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">pointer to location where to store + the start position, or %NULL</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="end_pos" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">pointer to location where to store + the end position, or %NULL</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </method> + <method name="fetch_pos" c:identifier="g_match_info_fetch_pos" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the position was fetched, %FALSE otherwise. If + the position cannot be fetched, @start_pos and @end_pos are left + unchanged</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="match_info" transfer-ownership="none"> + <doc xml:space="preserve">#GMatchInfo structure</doc> + <type name="MatchInfo" c:type="const GMatchInfo*"/> + </instance-parameter> + <parameter name="match_num" transfer-ownership="none"> + <doc xml:space="preserve">number of the sub expression</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="start_pos" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">pointer to location where to store + the start position, or %NULL</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="end_pos" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">pointer to location where to store + the end position, or %NULL</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </method> + <method name="free" c:identifier="g_match_info_free" version="2.14"> + <doc xml:space="preserve">If @match_info is not %NULL, calls g_match_info_unref(); otherwise does +nothing.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="match_info" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMatchInfo, or %NULL</doc> + <type name="MatchInfo" c:type="GMatchInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_match_count" c:identifier="g_match_info_get_match_count" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of matched substrings, or -1 if an error occurred</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="match_info" transfer-ownership="none"> + <doc xml:space="preserve">a #GMatchInfo structure</doc> + <type name="MatchInfo" c:type="const GMatchInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_regex" c:identifier="g_match_info_get_regex" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GRegex object used in @match_info</doc> + <type name="Regex" c:type="GRegex*"/> + </return-value> + <parameters> + <instance-parameter name="match_info" transfer-ownership="none"> + <doc xml:space="preserve">a #GMatchInfo</doc> + <type name="MatchInfo" c:type="const GMatchInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_string" c:identifier="g_match_info_get_string" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the string searched with @match_info</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="match_info" transfer-ownership="none"> + <doc xml:space="preserve">a #GMatchInfo</doc> + <type name="MatchInfo" c:type="const GMatchInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_partial_match" c:identifier="g_match_info_is_partial_match" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the match was partial, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="match_info" transfer-ownership="none"> + <doc xml:space="preserve">a #GMatchInfo structure</doc> + <type name="MatchInfo" c:type="const GMatchInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="matches" c:identifier="g_match_info_matches" version="2.14"> + <doc xml:space="preserve">Returns whether the previous match operation succeeded.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the previous match operation succeeded, + %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="match_info" transfer-ownership="none"> + <doc xml:space="preserve">a #GMatchInfo structure</doc> + <type name="MatchInfo" c:type="const GMatchInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="next" c:identifier="g_match_info_next" version="2.14" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE is the string matched, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="match_info" transfer-ownership="none"> + <doc xml:space="preserve">a #GMatchInfo structure</doc> + <type name="MatchInfo" c:type="GMatchInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_match_info_ref" version="2.30"> + <doc xml:space="preserve">Increases reference count of @match_info by 1.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">@match_info</doc> + <type name="MatchInfo" c:type="GMatchInfo*"/> + </return-value> + <parameters> + <instance-parameter name="match_info" transfer-ownership="none"> + <doc xml:space="preserve">a #GMatchInfo</doc> + <type name="MatchInfo" c:type="GMatchInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_match_info_unref" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="match_info" transfer-ownership="none"> + <doc xml:space="preserve">a #GMatchInfo</doc> + <type name="MatchInfo" c:type="GMatchInfo*"/> + </instance-parameter> + </parameters> + </method> + </record> + <record name="MemVTable" c:type="GMemVTable"> + <doc xml:space="preserve">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.</doc> + <field name="malloc"> + <callback name="malloc"> + <return-value transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="n_bytes" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </callback> + </field> + <field name="realloc"> + <callback name="realloc"> + <return-value transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="mem" transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_bytes" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </callback> + </field> + <field name="free"> + <callback name="free"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mem" transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="calloc"> + <callback name="calloc"> + <return-value transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="n_blocks" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="n_block_bytes" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </callback> + </field> + <field name="try_malloc"> + <callback name="try_malloc"> + <return-value transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="n_bytes" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </callback> + </field> + <field name="try_realloc"> + <callback name="try_realloc"> + <return-value transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="mem" transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_bytes" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <union name="Mutex" c:type="GMutex"> + <doc xml:space="preserve">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.</doc> + <field name="p" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="i" readable="0" private="1"> + <array zero-terminated="0" fixed-size="2"> + <type name="guint" c:type="guint"/> + </array> + </field> + <method name="clear" c:identifier="g_mutex_clear"> + <doc xml:space="preserve">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</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mutex" transfer-ownership="none"> + <doc xml:space="preserve">an initialized #GMutex</doc> + <type name="Mutex" c:type="GMutex*"/> + </instance-parameter> + </parameters> + </method> + <method name="init" c:identifier="g_mutex_init" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mutex" transfer-ownership="none"> + <doc xml:space="preserve">an uninitialized #GMutex</doc> + <type name="Mutex" c:type="GMutex*"/> + </instance-parameter> + </parameters> + </method> + <method name="lock" c:identifier="g_mutex_lock"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mutex" transfer-ownership="none"> + <doc xml:space="preserve">a #GMutex</doc> + <type name="Mutex" c:type="GMutex*"/> + </instance-parameter> + </parameters> + </method> + <method name="trylock" c:identifier="g_mutex_trylock"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @mutex could be locked</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mutex" transfer-ownership="none"> + <doc xml:space="preserve">a #GMutex</doc> + <type name="Mutex" c:type="GMutex*"/> + </instance-parameter> + </parameters> + </method> + <method name="unlock" c:identifier="g_mutex_unlock"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mutex" transfer-ownership="none"> + <doc xml:space="preserve">a #GMutex</doc> + <type name="Mutex" c:type="GMutex*"/> + </instance-parameter> + </parameters> + </method> + </union> + <function-macro name="NODE_IS_LEAF" c:identifier="G_NODE_IS_LEAF" introspectable="0"> + <doc xml:space="preserve">Returns %TRUE if a #GNode is a leaf node.</doc> + <parameters> + <parameter name="node"> + <doc xml:space="preserve">a #GNode</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="NODE_IS_ROOT" c:identifier="G_NODE_IS_ROOT" introspectable="0"> + <doc xml:space="preserve">Returns %TRUE if a #GNode is the root of a tree.</doc> + <parameters> + <parameter name="node"> + <doc xml:space="preserve">a #GNode</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="N_ELEMENTS" c:identifier="G_N_ELEMENTS" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="arr"> + <doc xml:space="preserve">the array</doc> + </parameter> + </parameters> + </function-macro> + <record name="Node" c:type="GNode"> + <doc xml:space="preserve">The #GNode struct represents one node in a [n-ary tree][glib-N-ary-Trees].</doc> + <field name="data" writable="1"> + <doc xml:space="preserve">contains the actual data of the node.</doc> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="next" writable="1"> + <doc xml:space="preserve">points to the node's next sibling (a sibling is another + #GNode with the same parent).</doc> + <type name="Node" c:type="GNode*"/> + </field> + <field name="prev" writable="1"> + <doc xml:space="preserve">points to the node's previous sibling.</doc> + <type name="Node" c:type="GNode*"/> + </field> + <field name="parent" writable="1"> + <doc xml:space="preserve">points to the parent of the #GNode, or is %NULL if the + #GNode is the root of the tree.</doc> + <type name="Node" c:type="GNode*"/> + </field> + <field name="children" writable="1"> + <doc xml:space="preserve">points to the first child of the #GNode. The other + children are accessed by using the @next pointer of each + child.</doc> + <type name="Node" c:type="GNode*"/> + </field> + <method name="child_index" c:identifier="g_node_child_index"> + <doc xml:space="preserve">Gets the position of the first child of a #GNode +which contains the given data.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the index of the child of @node which contains + @data, or -1 if the data is not found</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to find</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="child_position" c:identifier="g_node_child_position"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the position of @child with respect to its siblings</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + <parameter name="child" transfer-ownership="none"> + <doc xml:space="preserve">a child of @node</doc> + <type name="Node" c:type="GNode*"/> + </parameter> + </parameters> + </method> + <method name="children_foreach" c:identifier="g_node_children_foreach" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">which types of children are to be visited, one of + %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES</doc> + <type name="TraverseFlags" c:type="GTraverseFlags"/> + </parameter> + <parameter name="func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function to call for each visited node</doc> + <type name="NodeForeachFunc" c:type="GNodeForeachFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to the function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="copy" c:identifier="g_node_copy" introspectable="0"> + <doc xml:space="preserve">Recursively copies a #GNode (but does not deep-copy the data inside the +nodes, see g_node_copy_deep() if you need that).</doc> + <return-value> + <doc xml:space="preserve">a new #GNode containing the same data pointers</doc> + <type name="Node" c:type="GNode*"/> + </return-value> + <parameters> + <instance-parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + </parameters> + </method> + <method name="copy_deep" c:identifier="g_node_copy_deep" version="2.4" introspectable="0"> + <doc xml:space="preserve">Recursively copies a #GNode and its data.</doc> + <return-value> + <doc xml:space="preserve">a new #GNode containing copies of the data in @node.</doc> + <type name="Node" c:type="GNode*"/> + </return-value> + <parameters> + <instance-parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + <parameter name="copy_func" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">the function which is called to copy the data inside each node, + or %NULL to use the original data.</doc> + <type name="CopyFunc" c:type="GCopyFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @copy_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="depth" c:identifier="g_node_depth"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the depth of the #GNode</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + </parameters> + </method> + <method name="destroy" c:identifier="g_node_destroy"> + <doc xml:space="preserve">Removes @root and its children from the tree, freeing any memory +allocated.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="root" transfer-ownership="none"> + <doc xml:space="preserve">the root of the tree/subtree to destroy</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + </parameters> + </method> + <method name="find" c:identifier="g_node_find" introspectable="0"> + <doc xml:space="preserve">Finds a #GNode in a tree.</doc> + <return-value> + <doc xml:space="preserve">the found #GNode, or %NULL if the data is not found</doc> + <type name="Node" c:type="GNode*"/> + </return-value> + <parameters> + <instance-parameter name="root" transfer-ownership="none"> + <doc xml:space="preserve">the root #GNode of the tree to search</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + <parameter name="order" transfer-ownership="none"> + <doc xml:space="preserve">the order in which nodes are visited - %G_IN_ORDER, + %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER</doc> + <type name="TraverseType" c:type="GTraverseType"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">which types of children are to be searched, one of + %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES</doc> + <type name="TraverseFlags" c:type="GTraverseFlags"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to find</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="find_child" c:identifier="g_node_find_child" introspectable="0"> + <doc xml:space="preserve">Finds the first child of a #GNode with the given data.</doc> + <return-value> + <doc xml:space="preserve">the found child #GNode, or %NULL if the data is not found</doc> + <type name="Node" c:type="GNode*"/> + </return-value> + <parameters> + <instance-parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">which types of children are to be searched, one of + %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES</doc> + <type name="TraverseFlags" c:type="GTraverseFlags"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to find</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="first_sibling" c:identifier="g_node_first_sibling" introspectable="0"> + <doc xml:space="preserve">Gets the first sibling of a #GNode. +This could possibly be the node itself.</doc> + <return-value> + <doc xml:space="preserve">the first sibling of @node</doc> + <type name="Node" c:type="GNode*"/> + </return-value> + <parameters> + <instance-parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_root" c:identifier="g_node_get_root" introspectable="0"> + <doc xml:space="preserve">Gets the root of a tree.</doc> + <return-value> + <doc xml:space="preserve">the root of the tree</doc> + <type name="Node" c:type="GNode*"/> + </return-value> + <parameters> + <instance-parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + </parameters> + </method> + <method name="insert" c:identifier="g_node_insert" introspectable="0"> + <doc xml:space="preserve">Inserts a #GNode beneath the parent at the given position.</doc> + <return-value> + <doc xml:space="preserve">the inserted #GNode</doc> + <type name="Node" c:type="GNode*"/> + </return-value> + <parameters> + <instance-parameter name="parent" transfer-ownership="none"> + <doc xml:space="preserve">the #GNode to place @node under</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position to place @node at, with respect to its siblings + If position is -1, @node is inserted as the last child of @parent</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">the #GNode to insert</doc> + <type name="Node" c:type="GNode*"/> + </parameter> + </parameters> + </method> + <method name="insert_after" c:identifier="g_node_insert_after" introspectable="0"> + <doc xml:space="preserve">Inserts a #GNode beneath the parent after the given sibling.</doc> + <return-value> + <doc xml:space="preserve">the inserted #GNode</doc> + <type name="Node" c:type="GNode*"/> + </return-value> + <parameters> + <instance-parameter name="parent" transfer-ownership="none"> + <doc xml:space="preserve">the #GNode to place @node under</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + <parameter name="sibling" transfer-ownership="none"> + <doc xml:space="preserve">the sibling #GNode to place @node after. + If sibling is %NULL, the node is inserted as the first child of @parent.</doc> + <type name="Node" c:type="GNode*"/> + </parameter> + <parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">the #GNode to insert</doc> + <type name="Node" c:type="GNode*"/> + </parameter> + </parameters> + </method> + <method name="insert_before" c:identifier="g_node_insert_before" introspectable="0"> + <doc xml:space="preserve">Inserts a #GNode beneath the parent before the given sibling.</doc> + <return-value> + <doc xml:space="preserve">the inserted #GNode</doc> + <type name="Node" c:type="GNode*"/> + </return-value> + <parameters> + <instance-parameter name="parent" transfer-ownership="none"> + <doc xml:space="preserve">the #GNode to place @node under</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + <parameter name="sibling" transfer-ownership="none"> + <doc xml:space="preserve">the sibling #GNode to place @node before. + If sibling is %NULL, the node is inserted as the last child of @parent.</doc> + <type name="Node" c:type="GNode*"/> + </parameter> + <parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">the #GNode to insert</doc> + <type name="Node" c:type="GNode*"/> + </parameter> + </parameters> + </method> + <method name="is_ancestor" c:identifier="g_node_is_ancestor"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @node is an ancestor of @descendant</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + <parameter name="descendant" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode</doc> + <type name="Node" c:type="GNode*"/> + </parameter> + </parameters> + </method> + <method name="last_child" c:identifier="g_node_last_child" introspectable="0"> + <doc xml:space="preserve">Gets the last child of a #GNode.</doc> + <return-value> + <doc xml:space="preserve">the last child of @node, or %NULL if @node has no children</doc> + <type name="Node" c:type="GNode*"/> + </return-value> + <parameters> + <instance-parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode (must not be %NULL)</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + </parameters> + </method> + <method name="last_sibling" c:identifier="g_node_last_sibling" introspectable="0"> + <doc xml:space="preserve">Gets the last sibling of a #GNode. +This could possibly be the node itself.</doc> + <return-value> + <doc xml:space="preserve">the last sibling of @node</doc> + <type name="Node" c:type="GNode*"/> + </return-value> + <parameters> + <instance-parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + </parameters> + </method> + <method name="max_height" c:identifier="g_node_max_height"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the maximum height of the tree beneath @root</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="root" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + </parameters> + </method> + <method name="n_children" c:identifier="g_node_n_children"> + <doc xml:space="preserve">Gets the number of children of a #GNode.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of children of @node</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + </parameters> + </method> + <method name="n_nodes" c:identifier="g_node_n_nodes"> + <doc xml:space="preserve">Gets the number of nodes in a tree.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of nodes in the tree</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="root" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">which types of children are to be counted, one of + %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES</doc> + <type name="TraverseFlags" c:type="GTraverseFlags"/> + </parameter> + </parameters> + </method> + <method name="nth_child" c:identifier="g_node_nth_child" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the child of @node at index @n</doc> + <type name="Node" c:type="GNode*"/> + </return-value> + <parameters> + <instance-parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">the index of the desired child</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="prepend" c:identifier="g_node_prepend" introspectable="0"> + <doc xml:space="preserve">Inserts a #GNode as the first child of the given parent.</doc> + <return-value> + <doc xml:space="preserve">the inserted #GNode</doc> + <type name="Node" c:type="GNode*"/> + </return-value> + <parameters> + <instance-parameter name="parent" transfer-ownership="none"> + <doc xml:space="preserve">the #GNode to place the new #GNode under</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + <parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">the #GNode to insert</doc> + <type name="Node" c:type="GNode*"/> + </parameter> + </parameters> + </method> + <method name="reverse_children" c:identifier="g_node_reverse_children"> + <doc xml:space="preserve">Reverses the order of the children of a #GNode. +(It doesn't change the order of the grandchildren.)</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode.</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + </parameters> + </method> + <method name="traverse" c:identifier="g_node_traverse" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="root" transfer-ownership="none"> + <doc xml:space="preserve">the root #GNode of the tree to traverse</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + <parameter name="order" transfer-ownership="none"> + <doc xml:space="preserve">the order in which nodes are visited - %G_IN_ORDER, + %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER.</doc> + <type name="TraverseType" c:type="GTraverseType"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">which types of children are to be visited, one of + %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES</doc> + <type name="TraverseFlags" c:type="GTraverseFlags"/> + </parameter> + <parameter name="max_depth" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="func" transfer-ownership="none" closure="4"> + <doc xml:space="preserve">the function to call for each visited #GNode</doc> + <type name="NodeTraverseFunc" c:type="GNodeTraverseFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to the function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="unlink" c:identifier="g_node_unlink"> + <doc xml:space="preserve">Unlinks a #GNode from a tree, resulting in two separate trees.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">the #GNode to unlink, which becomes the root of a new tree</doc> + <type name="Node" c:type="GNode*"/> + </instance-parameter> + </parameters> + </method> + <function name="new" c:identifier="g_node_new" introspectable="0"> + <doc xml:space="preserve">Creates a new #GNode containing the given data. +Used to create the first node in a tree.</doc> + <return-value> + <doc xml:space="preserve">a new #GNode</doc> + <type name="Node" c:type="GNode*"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data of the new node</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + </record> + <callback name="NodeForeachFunc" c:type="GNodeForeachFunc"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode.</doc> + <type name="Node" c:type="GNode*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to g_node_children_foreach().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="NodeTraverseFunc" c:type="GNodeTraverseFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop the traversal.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">a #GNode.</doc> + <type name="Node" c:type="GNode*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to g_node_traverse().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <enumeration name="NormalizeMode" c:type="GNormalizeMode"> + <doc xml:space="preserve">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.</doc> + <member name="default" value="0" c:identifier="G_NORMALIZE_DEFAULT"> + <doc xml:space="preserve">standardize differences that do not affect the + text content, such as the above-mentioned accent representation</doc> + </member> + <member name="nfd" value="0" c:identifier="G_NORMALIZE_NFD"> + <doc xml:space="preserve">another name for %G_NORMALIZE_DEFAULT</doc> + </member> + <member name="default_compose" value="1" c:identifier="G_NORMALIZE_DEFAULT_COMPOSE"> + <doc xml:space="preserve">like %G_NORMALIZE_DEFAULT, but with + composed forms rather than a maximally decomposed form</doc> + </member> + <member name="nfc" value="1" c:identifier="G_NORMALIZE_NFC"> + <doc xml:space="preserve">another name for %G_NORMALIZE_DEFAULT_COMPOSE</doc> + </member> + <member name="all" value="2" c:identifier="G_NORMALIZE_ALL"> + <doc xml:space="preserve">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</doc> + </member> + <member name="nfkd" value="2" c:identifier="G_NORMALIZE_NFKD"> + <doc xml:space="preserve">another name for %G_NORMALIZE_ALL</doc> + </member> + <member name="all_compose" value="3" c:identifier="G_NORMALIZE_ALL_COMPOSE"> + <doc xml:space="preserve">like %G_NORMALIZE_ALL, but with composed + forms rather than a maximally decomposed form</doc> + </member> + <member name="nfkc" value="3" c:identifier="G_NORMALIZE_NFKC"> + <doc xml:space="preserve">another name for %G_NORMALIZE_ALL_COMPOSE</doc> + </member> + </enumeration> + <enumeration name="NumberParserError" version="2.54" c:type="GNumberParserError" glib:error-domain="g-number-parser-error-quark"> + <doc xml:space="preserve">Error codes returned by functions converting a string to a number.</doc> + <member name="invalid" value="0" c:identifier="G_NUMBER_PARSER_ERROR_INVALID"> + <doc xml:space="preserve">String was not a valid number.</doc> + </member> + <member name="out_of_bounds" value="1" c:identifier="G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS"> + <doc xml:space="preserve">String was a number, but out of bounds.</doc> + </member> + </enumeration> + <constant name="OPTION_REMAINING" value="" c:type="G_OPTION_REMAINING" version="2.6"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <record name="Once" c:type="GOnce" version="2.4"> + <doc xml:space="preserve">A #GOnce struct controls a one-time initialization function. Any +one-time initialization function must have its own unique #GOnce +struct.</doc> + <field name="status" writable="1"> + <doc xml:space="preserve">the status of the #GOnce</doc> + <type name="OnceStatus" c:type="volatile GOnceStatus"/> + </field> + <field name="retval" writable="1"> + <doc xml:space="preserve">the value returned by the call to the function, if @status + is %G_ONCE_STATUS_READY</doc> + <type name="gpointer" c:type="volatile gpointer"/> + </field> + <method name="impl" c:identifier="g_once_impl" introspectable="0"> + <return-value transfer-ownership="none" nullable="1"> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="once" transfer-ownership="none"> + <type name="Once" c:type="GOnce*"/> + </instance-parameter> + <parameter name="func" transfer-ownership="none"> + <type name="ThreadFunc" c:type="GThreadFunc"/> + </parameter> + <parameter name="arg" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <function name="init_enter" c:identifier="g_once_init_enter" version="2.14"> + <doc xml:space="preserve">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 +]| + +While @location has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the initialization section should be entered, + %FALSE and blocks otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="location" transfer-ownership="none"> + <doc xml:space="preserve">location of a static initializable variable + containing 0</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + </parameters> + </function> + <function name="init_leave" c:identifier="g_once_init_leave" version="2.14"> + <doc xml:space="preserve">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. + +While @location has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="location" transfer-ownership="none"> + <doc xml:space="preserve">location of a static initializable variable + containing 0</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">new non-0 value for *@value_location</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + </record> + <enumeration name="OnceStatus" version="2.4" c:type="GOnceStatus"> + <doc xml:space="preserve">The possible statuses of a one-time initialization function +controlled by a #GOnce struct.</doc> + <member name="notcalled" value="0" c:identifier="G_ONCE_STATUS_NOTCALLED"> + <doc xml:space="preserve">the function has not been called yet.</doc> + </member> + <member name="progress" value="1" c:identifier="G_ONCE_STATUS_PROGRESS"> + <doc xml:space="preserve">the function call is currently in progress.</doc> + </member> + <member name="ready" value="2" c:identifier="G_ONCE_STATUS_READY"> + <doc xml:space="preserve">the function has been called.</doc> + </member> + </enumeration> + <enumeration name="OptionArg" c:type="GOptionArg"> + <doc xml:space="preserve">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`.</doc> + <member name="none" value="0" c:identifier="G_OPTION_ARG_NONE"> + <doc xml:space="preserve">No extra argument. This is useful for simple flags.</doc> + </member> + <member name="string" value="1" c:identifier="G_OPTION_ARG_STRING"> + <doc xml:space="preserve">The option takes a UTF-8 string argument.</doc> + </member> + <member name="int" value="2" c:identifier="G_OPTION_ARG_INT"> + <doc xml:space="preserve">The option takes an integer argument.</doc> + </member> + <member name="callback" value="3" c:identifier="G_OPTION_ARG_CALLBACK"> + <doc xml:space="preserve">The option provides a callback (of type + #GOptionArgFunc) to parse the extra argument.</doc> + </member> + <member name="filename" value="4" c:identifier="G_OPTION_ARG_FILENAME"> + <doc xml:space="preserve">The option takes a filename as argument, which will + be in the GLib filename encoding rather than UTF-8.</doc> + </member> + <member name="string_array" value="5" c:identifier="G_OPTION_ARG_STRING_ARRAY"> + <doc xml:space="preserve">The option takes a string argument, multiple + uses of the option are collected into an array of strings.</doc> + </member> + <member name="filename_array" value="6" c:identifier="G_OPTION_ARG_FILENAME_ARRAY"> + <doc xml:space="preserve">The option takes a filename as argument, + multiple uses of the option are collected into an array of strings.</doc> + </member> + <member name="double" value="7" c:identifier="G_OPTION_ARG_DOUBLE"> + <doc xml:space="preserve">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</doc> + </member> + <member name="int64" value="8" c:identifier="G_OPTION_ARG_INT64"> + <doc xml:space="preserve">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</doc> + </member> + </enumeration> + <callback name="OptionArgFunc" c:type="GOptionArgFunc" throws="1"> + <doc xml:space="preserve">The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK +options.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the option was successfully parsed, %FALSE if an error + occurred, in which case @error should be set with g_set_error()</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="option_name" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">The value to be parsed.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">User data added to the #GOptionGroup containing the option when it + was created with g_option_group_new()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="OptionContext" c:type="GOptionContext" disguised="1"> + <doc xml:space="preserve">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.</doc> + <method name="add_group" c:identifier="g_option_context_add_group" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + <parameter name="group" transfer-ownership="full"> + <doc xml:space="preserve">the group to add</doc> + <type name="OptionGroup" c:type="GOptionGroup*"/> + </parameter> + </parameters> + </method> + <method name="add_main_entries" c:identifier="g_option_context_add_main_entries" version="2.6"> + <doc xml:space="preserve">A convenience function which creates a main group if it doesn't +exist, adds the @entries to it and sets the translation domain.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + <parameter name="entries" transfer-ownership="none"> + <doc xml:space="preserve">a %NULL-terminated array of #GOptionEntrys</doc> + <array c:type="const GOptionEntry*"> + <type name="OptionEntry" c:type="GOptionEntry"/> + </array> + </parameter> + <parameter name="translation_domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a translation domain to use for translating + the `--help` output for the options in @entries + with gettext(), or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="free" c:identifier="g_option_context_free" version="2.6"> + <doc xml:space="preserve">Frees context and all the groups which have been +added to it. + +Please note that parsed arguments need to be freed separately (see +#GOptionEntry).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_description" c:identifier="g_option_context_get_description" version="2.12"> + <doc xml:space="preserve">Returns the description. See g_option_context_set_description().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the description</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_help" c:identifier="g_option_context_get_help" version="2.14"> + <doc xml:space="preserve">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)`.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A newly allocated string containing the help text</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + <parameter name="main_help" transfer-ownership="none"> + <doc xml:space="preserve">if %TRUE, only include the main group</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="group" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the #GOptionGroup to create help for, or %NULL</doc> + <type name="OptionGroup" c:type="GOptionGroup*"/> + </parameter> + </parameters> + </method> + <method name="get_help_enabled" c:identifier="g_option_context_get_help_enabled" version="2.6"> + <doc xml:space="preserve">Returns whether automatic `--help` generation +is turned on for @context. See g_option_context_set_help_enabled().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if automatic help generation is turned on.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_ignore_unknown_options" c:identifier="g_option_context_get_ignore_unknown_options" version="2.6"> + <doc xml:space="preserve">Returns whether unknown options are ignored or not. See +g_option_context_set_ignore_unknown_options().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if unknown options are ignored.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_main_group" c:identifier="g_option_context_get_main_group" version="2.6"> + <doc xml:space="preserve">Returns a pointer to the main group of @context.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="OptionGroup" c:type="GOptionGroup*"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_strict_posix" c:identifier="g_option_context_get_strict_posix" version="2.44"> + <doc xml:space="preserve">Returns whether strict POSIX code is enabled. + +See g_option_context_set_strict_posix() for more information.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if strict POSIX is enabled, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_summary" c:identifier="g_option_context_get_summary" version="2.12"> + <doc xml:space="preserve">Returns the summary. See g_option_context_set_summary().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the summary</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="parse" c:identifier="g_option_context_parse" version="2.6" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the parsing was successful, + %FALSE if an error occurred</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + <parameter name="argc" direction="inout" caller-allocates="0" transfer-ownership="full" optional="1"> + <doc xml:space="preserve">a pointer to the number of command line arguments</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="argv" direction="inout" caller-allocates="0" transfer-ownership="full" optional="1"> + <doc xml:space="preserve">a pointer to the array of command line arguments</doc> + <array length="0" zero-terminated="0" c:type="gchar***"> + <type name="utf8" c:type="gchar**"/> + </array> + </parameter> + </parameters> + </method> + <method name="parse_strv" c:identifier="g_option_context_parse_strv" version="2.40" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the parsing was successful, + %FALSE if an error occurred</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + <parameter name="arguments" direction="inout" caller-allocates="0" transfer-ownership="full" optional="1"> + <doc xml:space="preserve">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().</doc> + <array zero-terminated="0" c:type="gchar***"> + <type name="utf8" c:type="gchar**"/> + </array> + </parameter> + </parameters> + </method> + <method name="set_description" c:identifier="g_option_context_set_description" version="2.12"> + <doc xml:space="preserve">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()).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + <parameter name="description" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string to be shown in `--help` output + after the list of options, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_help_enabled" c:identifier="g_option_context_set_help_enabled" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + <parameter name="help_enabled" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to enable `--help`, %FALSE to disable it</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_ignore_unknown_options" c:identifier="g_option_context_set_ignore_unknown_options" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + <parameter name="ignore_unknown" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to ignore unknown options, %FALSE to produce + an error when unknown options are met</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_main_group" c:identifier="g_option_context_set_main_group" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + <parameter name="group" transfer-ownership="full"> + <doc xml:space="preserve">the group to set as main group</doc> + <type name="OptionGroup" c:type="GOptionGroup*"/> + </parameter> + </parameters> + </method> + <method name="set_strict_posix" c:identifier="g_option_context_set_strict_posix" version="2.44"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + <parameter name="strict_posix" transfer-ownership="none"> + <doc xml:space="preserve">the new value</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_summary" c:identifier="g_option_context_set_summary" version="2.12"> + <doc xml:space="preserve">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()).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + <parameter name="summary" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string to be shown in `--help` output + before the list of options, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_translate_func" c:identifier="g_option_context_set_translate_func" version="2.12"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + <parameter name="func" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="1" destroy="2"> + <doc xml:space="preserve">the #GTranslateFunc, or %NULL</doc> + <type name="TranslateFunc" c:type="GTranslateFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to @func, or %NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy_notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a function which gets called to free @data, or %NULL</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="set_translation_domain" c:identifier="g_option_context_set_translation_domain" version="2.12"> + <doc xml:space="preserve">A convenience function to use gettext() for translating +user-visible strings.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </instance-parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">the domain to use</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <function name="new" c:identifier="g_option_context_new" version="2.6" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">a newly created #GOptionContext, which must be + freed with g_option_context_free() after use.</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </return-value> + <parameters> + <parameter name="parameter_string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string which is displayed in + the first line of `--help` output, after the usage summary + `programname [OPTION...]`</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + </record> + <record name="OptionEntry" c:type="GOptionEntry"> + <doc xml:space="preserve">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().</doc> + <field name="long_name" writable="1"> + <doc xml:space="preserve">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`.</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="short_name" writable="1"> + <doc xml:space="preserve">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.</doc> + <type name="gchar" c:type="gchar"/> + </field> + <field name="flags" writable="1"> + <doc xml:space="preserve">Flags from #GOptionFlags</doc> + <type name="gint" c:type="gint"/> + </field> + <field name="arg" writable="1"> + <doc xml:space="preserve">The type of the option, as a #GOptionArg</doc> + <type name="OptionArg" c:type="GOptionArg"/> + </field> + <field name="arg_data" writable="1"> + <doc xml:space="preserve">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().</doc> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="description" writable="1"> + <doc xml:space="preserve">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().</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="arg_description" writable="1"> + <doc xml:space="preserve">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().</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + </record> + <enumeration name="OptionError" c:type="GOptionError" glib:error-domain="g-option-error-quark"> + <doc xml:space="preserve">Error codes returned by option parsing.</doc> + <member name="unknown_option" value="0" c:identifier="G_OPTION_ERROR_UNKNOWN_OPTION"> + <doc xml:space="preserve">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().</doc> + </member> + <member name="bad_value" value="1" c:identifier="G_OPTION_ERROR_BAD_VALUE"> + <doc xml:space="preserve">A value couldn't be parsed.</doc> + </member> + <member name="failed" value="2" c:identifier="G_OPTION_ERROR_FAILED"> + <doc xml:space="preserve">A #GOptionArgFunc callback failed.</doc> + </member> + </enumeration> + <callback name="OptionErrorFunc" c:type="GOptionErrorFunc" throws="1"> + <doc xml:space="preserve">The type of function to be used as callback when a parse error occurs.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">The active #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </parameter> + <parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">The group to which the function belongs</doc> + <type name="OptionGroup" c:type="GOptionGroup*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">User data added to the #GOptionGroup containing the option when it + was created with g_option_group_new()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <bitfield name="OptionFlags" c:type="GOptionFlags"> + <doc xml:space="preserve">Flags which modify individual options.</doc> + <member name="none" value="0" c:identifier="G_OPTION_FLAG_NONE"> + <doc xml:space="preserve">No flags. Since: 2.42.</doc> + </member> + <member name="hidden" value="1" c:identifier="G_OPTION_FLAG_HIDDEN"> + <doc xml:space="preserve">The option doesn't appear in `--help` output.</doc> + </member> + <member name="in_main" value="2" c:identifier="G_OPTION_FLAG_IN_MAIN"> + <doc xml:space="preserve">The option appears in the main section of the + `--help` output, even if it is defined in a group.</doc> + </member> + <member name="reverse" value="4" c:identifier="G_OPTION_FLAG_REVERSE"> + <doc xml:space="preserve">For options of the %G_OPTION_ARG_NONE kind, this + flag indicates that the sense of the option is reversed.</doc> + </member> + <member name="no_arg" value="8" c:identifier="G_OPTION_FLAG_NO_ARG"> + <doc xml:space="preserve">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</doc> + </member> + <member name="filename" value="16" c:identifier="G_OPTION_FLAG_FILENAME"> + <doc xml:space="preserve">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</doc> + </member> + <member name="optional_arg" value="32" c:identifier="G_OPTION_FLAG_OPTIONAL_ARG"> + <doc xml:space="preserve">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</doc> + </member> + <member name="noalias" value="64" c:identifier="G_OPTION_FLAG_NOALIAS"> + <doc xml:space="preserve">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.</doc> + </member> + </bitfield> + <record name="OptionGroup" c:type="GOptionGroup" glib:type-name="GOptionGroup" glib:get-type="g_option_group_get_type" c:symbol-prefix="option_group"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_option_group_new" version="2.6"> + <doc xml:space="preserve">Creates a new #GOptionGroup.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created option group. It should be added + to a #GOptionContext or freed with g_option_group_unref().</doc> + <type name="OptionGroup" c:type="GOptionGroup*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name for the option group, this is used to provide + help for the options in this group with `--help-`@name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="description" transfer-ownership="none"> + <doc xml:space="preserve">a description for this group to be shown in + `--help`. This string is translated using the translation + domain or translation function of the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="help_description" transfer-ownership="none"> + <doc xml:space="preserve">a description for the `--help-`@name option. + This string is translated using the translation domain or translation function + of the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">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</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a function that will be called to free @user_data, or %NULL</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </constructor> + <method name="add_entries" c:identifier="g_option_group_add_entries" version="2.6"> + <doc xml:space="preserve">Adds the options specified in @entries to @group.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionGroup</doc> + <type name="OptionGroup" c:type="GOptionGroup*"/> + </instance-parameter> + <parameter name="entries" transfer-ownership="none"> + <doc xml:space="preserve">a %NULL-terminated array of #GOptionEntrys</doc> + <array c:type="const GOptionEntry*"> + <type name="OptionEntry" c:type="GOptionEntry"/> + </array> + </parameter> + </parameters> + </method> + <method name="free" c:identifier="g_option_group_free" version="2.6" deprecated="1" deprecated-version="2.44"> + <doc xml:space="preserve">Frees a #GOptionGroup. Note that you must not free groups +which have been added to a #GOptionContext.</doc> + <doc-deprecated xml:space="preserve">Use g_option_group_unref() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionGroup</doc> + <type name="OptionGroup" c:type="GOptionGroup*"/> + </instance-parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_option_group_ref" version="2.44"> + <doc xml:space="preserve">Increments the reference count of @group by one.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GOptionGroup</doc> + <type name="OptionGroup" c:type="GOptionGroup*"/> + </return-value> + <parameters> + <instance-parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionGroup</doc> + <type name="OptionGroup" c:type="GOptionGroup*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_error_hook" c:identifier="g_option_group_set_error_hook" version="2.6" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionGroup</doc> + <type name="OptionGroup" c:type="GOptionGroup*"/> + </instance-parameter> + <parameter name="error_func" transfer-ownership="none"> + <doc xml:space="preserve">a function to call when an error occurs</doc> + <type name="OptionErrorFunc" c:type="GOptionErrorFunc"/> + </parameter> + </parameters> + </method> + <method name="set_parse_hooks" c:identifier="g_option_group_set_parse_hooks" version="2.6" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionGroup</doc> + <type name="OptionGroup" c:type="GOptionGroup*"/> + </instance-parameter> + <parameter name="pre_parse_func" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a function to call before parsing, or %NULL</doc> + <type name="OptionParseFunc" c:type="GOptionParseFunc"/> + </parameter> + <parameter name="post_parse_func" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a function to call after parsing, or %NULL</doc> + <type name="OptionParseFunc" c:type="GOptionParseFunc"/> + </parameter> + </parameters> + </method> + <method name="set_translate_func" c:identifier="g_option_group_set_translate_func" version="2.6"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionGroup</doc> + <type name="OptionGroup" c:type="GOptionGroup*"/> + </instance-parameter> + <parameter name="func" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="1" destroy="2"> + <doc xml:space="preserve">the #GTranslateFunc, or %NULL</doc> + <type name="TranslateFunc" c:type="GTranslateFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to @func, or %NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy_notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a function which gets called to free @data, or %NULL</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="set_translation_domain" c:identifier="g_option_group_set_translation_domain" version="2.6"> + <doc xml:space="preserve">A convenience function to use gettext() for translating +user-visible strings.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionGroup</doc> + <type name="OptionGroup" c:type="GOptionGroup*"/> + </instance-parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">the domain to use</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_option_group_unref" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">a #GOptionGroup</doc> + <type name="OptionGroup" c:type="GOptionGroup*"/> + </instance-parameter> + </parameters> + </method> + </record> + <callback name="OptionParseFunc" c:type="GOptionParseFunc" throws="1"> + <doc xml:space="preserve">The type of function that can be called before and after parsing.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the function completed successfully, %FALSE if an error + occurred, in which case @error should be set with g_set_error()</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">The active #GOptionContext</doc> + <type name="OptionContext" c:type="GOptionContext*"/> + </parameter> + <parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">The group to which the function belongs</doc> + <type name="OptionGroup" c:type="GOptionGroup*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">User data added to the #GOptionGroup containing the option when it + was created with g_option_group_new()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <constant name="PDP_ENDIAN" value="3412" c:type="G_PDP_ENDIAN"> + <doc xml:space="preserve">Specifies one of the possible types of byte order +(currently unused). See #G_BYTE_ORDER.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="PI" value="3.141593" c:type="G_PI"> + <doc xml:space="preserve">The value of pi (ratio of circle's circumference to its diameter).</doc> + <type name="gdouble" c:type="gdouble"/> + </constant> + <constant name="PID_FORMAT" value="i" c:type="G_PID_FORMAT" version="2.50"> + <doc xml:space="preserve">A format specifier that can be used in printf()-style format strings +when printing a #GPid.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="PI_2" value="1.570796" c:type="G_PI_2"> + <doc xml:space="preserve">Pi divided by 2.</doc> + <type name="gdouble" c:type="gdouble"/> + </constant> + <constant name="PI_4" value="0.785398" c:type="G_PI_4"> + <doc xml:space="preserve">Pi divided by 4.</doc> + <type name="gdouble" c:type="gdouble"/> + </constant> + <constant name="POLLFD_FORMAT" value="%d" c:type="G_POLLFD_FORMAT"> + <doc xml:space="preserve">A format specifier that can be used in printf()-style format strings +when printing the @fd member of a #GPollFD.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="PRIORITY_DEFAULT" value="0" c:type="G_PRIORITY_DEFAULT"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="PRIORITY_DEFAULT_IDLE" value="200" c:type="G_PRIORITY_DEFAULT_IDLE"> + <doc xml:space="preserve">Use this for default priority idle functions. + +In GLib this priority is used when adding idle functions with +g_idle_add().</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="PRIORITY_HIGH" value="-100" c:type="G_PRIORITY_HIGH"> + <doc xml:space="preserve">Use this for high priority event sources. + +It is not used within GLib or GTK+.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="PRIORITY_HIGH_IDLE" value="100" c:type="G_PRIORITY_HIGH_IDLE"> + <doc xml:space="preserve">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.)</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="PRIORITY_LOW" value="300" c:type="G_PRIORITY_LOW"> + <doc xml:space="preserve">Use this for very low priority background tasks. + +It is not used within GLib or GTK+.</doc> + <type name="gint" c:type="gint"/> + </constant> + <function-macro name="PRIVATE_INIT" c:identifier="G_PRIVATE_INIT" version="2.32" introspectable="0"> + <doc xml:space="preserve">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)); +} +]|</doc> + <parameters> + <parameter name="notify"> + <doc xml:space="preserve">a #GDestroyNotify</doc> + </parameter> + </parameters> + </function-macro> + <record name="PatternSpec" c:type="GPatternSpec" disguised="1"> + <doc xml:space="preserve">A GPatternSpec struct is the 'compiled' form of a pattern. This +structure is opaque and its fields cannot be accessed directly.</doc> + <method name="equal" c:identifier="g_pattern_spec_equal"> + <doc xml:space="preserve">Compares two compiled pattern specs and returns whether they will +match the same set of strings.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Whether the compiled patterns are equal</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="pspec1" transfer-ownership="none"> + <doc xml:space="preserve">a #GPatternSpec</doc> + <type name="PatternSpec" c:type="GPatternSpec*"/> + </instance-parameter> + <parameter name="pspec2" transfer-ownership="none"> + <doc xml:space="preserve">another #GPatternSpec</doc> + <type name="PatternSpec" c:type="GPatternSpec*"/> + </parameter> + </parameters> + </method> + <method name="free" c:identifier="g_pattern_spec_free"> + <doc xml:space="preserve">Frees the memory allocated for the #GPatternSpec.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a #GPatternSpec</doc> + <type name="PatternSpec" c:type="GPatternSpec*"/> + </instance-parameter> + </parameters> + </method> + <function name="new" c:identifier="g_pattern_spec_new" introspectable="0"> + <doc xml:space="preserve">Compiles a pattern to a #GPatternSpec.</doc> + <return-value> + <doc xml:space="preserve">a newly-allocated #GPatternSpec</doc> + <type name="PatternSpec" c:type="GPatternSpec*"/> + </return-value> + <parameters> + <parameter name="pattern" transfer-ownership="none"> + <doc xml:space="preserve">a zero-terminated UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + </record> + <record name="PollFD" c:type="GPollFD" glib:type-name="GPollFD" glib:get-type="g_pollfd_get_type" c:symbol-prefix="pollfd"> + <doc xml:space="preserve">Represents a file descriptor, which events to poll for, and which events +occurred.</doc> + <field name="fd" writable="1"> + <doc xml:space="preserve">the file descriptor to poll (or a HANDLE on Win32)</doc> + <type name="gint" c:type="gint"/> + </field> + <field name="events" writable="1"> + <doc xml:space="preserve">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.</doc> + <type name="gushort" c:type="gushort"/> + </field> + <field name="revents" writable="1"> + <doc xml:space="preserve">a bitwise combination of flags from #GIOCondition, returned + from the poll() function to indicate which events occurred.</doc> + <type name="gushort" c:type="gushort"/> + </field> + </record> + <callback name="PollFunc" c:type="GPollFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of #GPollFD elements which have events or errors + reported, or -1 if an error occurred.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="ufds" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GPollFD elements</doc> + <type name="PollFD" c:type="GPollFD*"/> + </parameter> + <parameter name="nfsd" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements in @ufds</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="timeout_" transfer-ownership="none"> + <doc xml:space="preserve">the maximum time to wait for an event of the file descriptors. + A negative value indicates an infinite timeout.</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </callback> + <callback name="PrintFunc" c:type="GPrintFunc"> + <doc xml:space="preserve">Specifies the type of the print handler functions. +These are called with the complete formatted string to output.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the message to output</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + <record name="Private" c:type="GPrivate"> + <doc xml:space="preserve">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.</doc> + <field name="p" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="notify" readable="0" private="1"> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </field> + <field name="future" readable="0" private="1"> + <array zero-terminated="0" fixed-size="2"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + <method name="get" c:identifier="g_private_get"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the thread-local value</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a #GPrivate</doc> + <type name="Private" c:type="GPrivate*"/> + </instance-parameter> + </parameters> + </method> + <method name="replace" c:identifier="g_private_replace" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a #GPrivate</doc> + <type name="Private" c:type="GPrivate*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the new value</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="set" c:identifier="g_private_set"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a #GPrivate</doc> + <type name="Private" c:type="GPrivate*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the new value</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + </record> + <record name="PtrArray" c:type="GPtrArray" glib:type-name="GPtrArray" glib:get-type="g_ptr_array_get_type" c:symbol-prefix="ptr_array"> + <doc xml:space="preserve">Contains the public fields of a pointer array.</doc> + <field name="pdata" writable="1"> + <doc xml:space="preserve">points to the array of pointers, which may be moved when the + array grows</doc> + <type name="gpointer" c:type="gpointer*"/> + </field> + <field name="len" writable="1"> + <doc xml:space="preserve">number of pointers in the array</doc> + <type name="guint" c:type="guint"/> + </field> + <function name="add" c:identifier="g_ptr_array_add" introspectable="0"> + <doc xml:space="preserve">Adds a pointer to the end of the pointer array. The array will grow +in size automatically if necessary.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the pointer to add</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="copy" c:identifier="g_ptr_array_copy" version="2.62" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a deep copy of the initial #GPtrArray.</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">#GPtrArray to duplicate</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="func" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">a copy function used to copy every element in the array</doc> + <type name="CopyFunc" c:type="GCopyFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to the copy function @func, or %NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="extend" c:identifier="g_ptr_array_extend" version="2.62" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array_to_extend" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray.</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray to add to the end of @array_to_extend.</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="func" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">a copy function used to copy every element in the array</doc> + <type name="CopyFunc" c:type="GCopyFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to the copy function @func, or %NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="extend_and_steal" c:identifier="g_ptr_array_extend_and_steal" version="2.62" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array_to_extend" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray.</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="array" transfer-ownership="container"> + <doc xml:space="preserve">a #GPtrArray to add to the end of + @array_to_extend.</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + </parameters> + </function> + <function name="find" c:identifier="g_ptr_array_find" version="2.54" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @needle is one of the elements of @haystack</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="haystack" transfer-ownership="none"> + <doc xml:space="preserve">pointer array to be searched</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="needle" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">pointer to look for</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="index_" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the index of + the element, if found</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </function> + <function name="find_with_equal_func" c:identifier="g_ptr_array_find_with_equal_func" version="2.54" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @needle is one of the elements of @haystack</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="haystack" transfer-ownership="none"> + <doc xml:space="preserve">pointer array to be searched</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="needle" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">pointer to look for</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="equal_func" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the function to call for each element, which should + return %TRUE when the desired element is found; or %NULL to use pointer + equality</doc> + <type name="EqualFunc" c:type="GEqualFunc"/> + </parameter> + <parameter name="index_" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the index of + the element, if found</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </function> + <function name="foreach" c:identifier="g_ptr_array_foreach" version="2.4" introspectable="0"> + <doc xml:space="preserve">Calls a function for each element of a #GPtrArray. @func must not +add elements to or remove elements from the array.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function to call for each array element</doc> + <type name="Func" c:type="GFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to the function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="free" c:identifier="g_ptr_array_free" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the pointer array if @free_seg is + %FALSE, otherwise %NULL. The pointer array should be freed using g_free().</doc> + <type name="gpointer" c:type="gpointer*"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="free_seg" transfer-ownership="none"> + <doc xml:space="preserve">if %TRUE the actual pointer array is freed as well</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="insert" c:identifier="g_ptr_array_insert" version="2.40" introspectable="0"> + <doc xml:space="preserve">Inserts an element into the pointer array at the given index. The +array will grow in size automatically if necessary.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">the index to place the new element at, or -1 to append</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the pointer to add.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="new" c:identifier="g_ptr_array_new" introspectable="0"> + <doc xml:space="preserve">Creates a new #GPtrArray with a reference count of 1.</doc> + <return-value> + <doc xml:space="preserve">the new #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + </function> + <function name="new_full" c:identifier="g_ptr_array_new_full" version="2.30" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">A new #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="reserved_size" transfer-ownership="none"> + <doc xml:space="preserve">number of pointers preallocated</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="element_free_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">A function to free elements with + destroy @array or %NULL</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="new_with_free_func" c:identifier="g_ptr_array_new_with_free_func" version="2.22" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">A new #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="element_free_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">A function to free elements with + destroy @array or %NULL</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="ref" c:identifier="g_ptr_array_ref" version="2.22" introspectable="0"> + <doc xml:space="preserve">Atomically increments the reference count of @array by one. +This function is thread-safe and may be called from any thread.</doc> + <return-value> + <doc xml:space="preserve">The passed in #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + </parameters> + </function> + <function name="remove" c:identifier="g_ptr_array_remove" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the pointer is removed, %FALSE if the pointer + is not found in the array</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the pointer to remove</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="remove_fast" c:identifier="g_ptr_array_remove_fast" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the pointer was found in the array</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the pointer to remove</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="remove_index" c:identifier="g_ptr_array_remove_index" introspectable="0"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the pointer which was removed</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">the index of the pointer to remove</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="remove_index_fast" c:identifier="g_ptr_array_remove_index_fast" introspectable="0"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the pointer which was removed</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">the index of the pointer to remove</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="remove_range" c:identifier="g_ptr_array_remove_range" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the @array</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a @GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">the index of the first pointer to remove</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the number of pointers to remove</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="set_free_func" c:identifier="g_ptr_array_set_free_func" version="2.22" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">A #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="element_free_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">A function to free elements with + destroy @array or %NULL</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="set_size" c:identifier="g_ptr_array_set_size" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the new length of the pointer array</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="sized_new" c:identifier="g_ptr_array_sized_new" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the new #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </return-value> + <parameters> + <parameter name="reserved_size" transfer-ownership="none"> + <doc xml:space="preserve">number of pointers preallocated</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="sort" c:identifier="g_ptr_array_sort" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="compare_func" transfer-ownership="none"> + <doc xml:space="preserve">comparison function</doc> + <type name="CompareFunc" c:type="GCompareFunc"/> + </parameter> + </parameters> + </function> + <function name="sort_with_data" c:identifier="g_ptr_array_sort_with_data" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="compare_func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">comparison function</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @compare_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="steal" c:identifier="g_ptr_array_steal" version="2.64" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the element data, which should be + freed using g_free().</doc> + <type name="gpointer" c:type="gpointer*"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray.</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="len" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">pointer to retrieve the number of + elements of the original array</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </function> + <function name="steal_index" c:identifier="g_ptr_array_steal_index" version="2.58" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the pointer which was removed</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">the index of the pointer to steal</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="steal_index_fast" c:identifier="g_ptr_array_steal_index_fast" version="2.58" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the pointer which was removed</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">the index of the pointer to steal</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="unref" c:identifier="g_ptr_array_unref" version="2.22" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">A #GPtrArray</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + </parameters> + </function> + </record> + <record name="Queue" c:type="GQueue"> + <doc xml:space="preserve">Contains the public fields of a +[Queue][glib-Double-ended-Queues].</doc> + <field name="head" writable="1"> + <doc xml:space="preserve">a pointer to the first element of the queue</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </field> + <field name="tail" writable="1"> + <doc xml:space="preserve">a pointer to the last element of the queue</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </field> + <field name="length" writable="1"> + <doc xml:space="preserve">the number of elements in the queue</doc> + <type name="guint" c:type="guint"/> + </field> + <method name="clear" c:identifier="g_queue_clear" version="2.14"> + <doc xml:space="preserve">Removes all the elements in @queue. If queue elements contain +dynamically-allocated memory, they should be freed first.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="clear_full" c:identifier="g_queue_clear_full" version="2.60"> + <doc xml:space="preserve">Convenience method, which frees all the memory used by a #GQueue, +and calls the provided @free_func on each item in the #GQueue.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="free_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">the function to be called to free memory allocated</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="copy" c:identifier="g_queue_copy" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">a copy of @queue</doc> + <type name="Queue" c:type="GQueue*"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="delete_link" c:identifier="g_queue_delete_link" version="2.4" introspectable="0"> + <doc xml:space="preserve">Removes @link_ from @queue and frees it. + +@link_ must be part of @queue.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="link_" transfer-ownership="none"> + <doc xml:space="preserve">a #GList link that must be part of @queue</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </method> + <method name="find" c:identifier="g_queue_find" version="2.4" introspectable="0"> + <doc xml:space="preserve">Finds the first link in @queue which contains @data.</doc> + <return-value> + <doc xml:space="preserve">the first link in @queue which contains @data</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to find</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="find_custom" c:identifier="g_queue_find_custom" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the found link, or %NULL if it wasn't found</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @func</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="func" transfer-ownership="none"> + <doc xml:space="preserve">a #GCompareFunc to call for each element. It should return 0 + when the desired element is found</doc> + <type name="CompareFunc" c:type="GCompareFunc"/> + </parameter> + </parameters> + </method> + <method name="foreach" c:identifier="g_queue_foreach" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="func" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">the function to call for each element's data</doc> + <type name="Func" c:type="GFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to @func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="free" c:identifier="g_queue_free"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="free_full" c:identifier="g_queue_free_full" version="2.32"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="free_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">the function to be called to free each element's data</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="get_length" c:identifier="g_queue_get_length" version="2.4"> + <doc xml:space="preserve">Returns the number of items in @queue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of items in @queue</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="index" c:identifier="g_queue_index" version="2.4"> + <doc xml:space="preserve">Returns the position of the first element in @queue which contains @data.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the position of the first element in @queue which + contains @data, or -1 if no element in @queue contains @data</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to find</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="init" c:identifier="g_queue_init" version="2.14"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">an uninitialized #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="insert_after" c:identifier="g_queue_insert_after" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="sibling" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GList link that must be part of @queue, or %NULL to + push at the head of the queue.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to insert</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="insert_after_link" c:identifier="g_queue_insert_after_link" version="2.62" introspectable="0"> + <doc xml:space="preserve">Inserts @link_ into @queue after @sibling. + +@sibling must be part of @queue.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="sibling" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GList link that must be part of @queue, or %NULL to + push at the head of the queue.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="link_" transfer-ownership="none"> + <doc xml:space="preserve">a #GList link to insert which must not be part of any other list.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </method> + <method name="insert_before" c:identifier="g_queue_insert_before" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="sibling" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GList link that must be part of @queue, or %NULL to + push at the tail of the queue.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to insert</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="insert_before_link" c:identifier="g_queue_insert_before_link" version="2.62" introspectable="0"> + <doc xml:space="preserve">Inserts @link_ into @queue before @sibling. + +@sibling must be part of @queue.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="sibling" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GList link that must be part of @queue, or %NULL to + push at the tail of the queue.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="link_" transfer-ownership="none"> + <doc xml:space="preserve">a #GList link to insert which must not be part of any other list.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </method> + <method name="insert_sorted" c:identifier="g_queue_insert_sorted" version="2.4" introspectable="0"> + <doc xml:space="preserve">Inserts @data into @queue using @func to determine the new position.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to insert</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">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.</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="is_empty" c:identifier="g_queue_is_empty"> + <doc xml:space="preserve">Returns %TRUE if the queue is empty.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the queue is empty</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue.</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="link_index" c:identifier="g_queue_link_index" version="2.4" introspectable="0"> + <doc xml:space="preserve">Returns the position of @link_ in @queue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the position of @link_, or -1 if the link is + not part of @queue</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="link_" transfer-ownership="none"> + <doc xml:space="preserve">a #GList link</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </method> + <method name="peek_head" c:identifier="g_queue_peek_head"> + <doc xml:space="preserve">Returns the first element of the queue.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the data of the first element in the queue, or %NULL + if the queue is empty</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="peek_head_link" c:identifier="g_queue_peek_head_link" version="2.4" introspectable="0"> + <doc xml:space="preserve">Returns the first link in @queue.</doc> + <return-value> + <doc xml:space="preserve">the first link in @queue, or %NULL if @queue is empty</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="peek_nth" c:identifier="g_queue_peek_nth" version="2.4"> + <doc xml:space="preserve">Returns the @n'th element of @queue.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the data for the @n'th element of @queue, + or %NULL if @n is off the end of @queue</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">the position of the element</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="peek_nth_link" c:identifier="g_queue_peek_nth_link" version="2.4" introspectable="0"> + <doc xml:space="preserve">Returns the link at the given position</doc> + <return-value> + <doc xml:space="preserve">the link at the @n'th position, or %NULL + if @n is off the end of the list</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">the position of the link</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="peek_tail" c:identifier="g_queue_peek_tail"> + <doc xml:space="preserve">Returns the last element of the queue.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the data of the last element in the queue, or %NULL + if the queue is empty</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="peek_tail_link" c:identifier="g_queue_peek_tail_link" version="2.4" introspectable="0"> + <doc xml:space="preserve">Returns the last link in @queue.</doc> + <return-value> + <doc xml:space="preserve">the last link in @queue, or %NULL if @queue is empty</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="pop_head" c:identifier="g_queue_pop_head"> + <doc xml:space="preserve">Removes the first element of the queue and returns its data.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the data of the first element in the queue, or %NULL + if the queue is empty</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="pop_head_link" c:identifier="g_queue_pop_head_link" introspectable="0"> + <doc xml:space="preserve">Removes and returns the first element of the queue.</doc> + <return-value> + <doc xml:space="preserve">the #GList element at the head of the queue, or %NULL + if the queue is empty</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="pop_nth" c:identifier="g_queue_pop_nth" version="2.4"> + <doc xml:space="preserve">Removes the @n'th element of @queue and returns its data.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the element's data, or %NULL if @n is off the end of @queue</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">the position of the element</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="pop_nth_link" c:identifier="g_queue_pop_nth_link" version="2.4" introspectable="0"> + <doc xml:space="preserve">Removes and returns the link at the given position.</doc> + <return-value> + <doc xml:space="preserve">the @n'th link, or %NULL if @n is off the end of @queue</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">the link's position</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="pop_tail" c:identifier="g_queue_pop_tail"> + <doc xml:space="preserve">Removes the last element of the queue and returns its data.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the data of the last element in the queue, or %NULL + if the queue is empty</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="pop_tail_link" c:identifier="g_queue_pop_tail_link" introspectable="0"> + <doc xml:space="preserve">Removes and returns the last element of the queue.</doc> + <return-value> + <doc xml:space="preserve">the #GList element at the tail of the queue, or %NULL + if the queue is empty</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="push_head" c:identifier="g_queue_push_head"> + <doc xml:space="preserve">Adds a new element at the head of the queue.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue.</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new element.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="push_head_link" c:identifier="g_queue_push_head_link" introspectable="0"> + <doc xml:space="preserve">Adds a new element at the head of the queue.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="link_" transfer-ownership="none"> + <doc xml:space="preserve">a single #GList element, not a list with more than one element</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </method> + <method name="push_nth" c:identifier="g_queue_push_nth" version="2.4"> + <doc xml:space="preserve">Inserts a new element into @queue at the given position.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new element</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="push_nth_link" c:identifier="g_queue_push_nth_link" version="2.4" introspectable="0"> + <doc xml:space="preserve">Inserts @link into @queue at the given position.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="link_" transfer-ownership="none"> + <doc xml:space="preserve">the link to add to @queue</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </method> + <method name="push_tail" c:identifier="g_queue_push_tail"> + <doc xml:space="preserve">Adds a new element at the tail of the queue.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new element</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="push_tail_link" c:identifier="g_queue_push_tail_link" introspectable="0"> + <doc xml:space="preserve">Adds a new element at the tail of the queue.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="link_" transfer-ownership="none"> + <doc xml:space="preserve">a single #GList element, not a list with more than one element</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </method> + <method name="remove" c:identifier="g_queue_remove" version="2.4"> + <doc xml:space="preserve">Removes the first element in @queue that contains @data.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @data was found and removed from @queue</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to remove</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="remove_all" c:identifier="g_queue_remove_all" version="2.4"> + <doc xml:space="preserve">Remove all elements whose data equals @data from @queue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of elements removed from @queue</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to remove</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="reverse" c:identifier="g_queue_reverse" version="2.4"> + <doc xml:space="preserve">Reverses the order of the items in @queue.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + </parameters> + </method> + <method name="sort" c:identifier="g_queue_sort" version="2.4" introspectable="0"> + <doc xml:space="preserve">Sorts @queue using @compare_func.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="compare_func" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">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.</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @compare_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="unlink" c:identifier="g_queue_unlink" version="2.4" introspectable="0"> + <doc xml:space="preserve">Unlinks @link_ so that it will no longer be part of @queue. +The link is not freed. + +@link_ must be part of @queue.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="queue" transfer-ownership="none"> + <doc xml:space="preserve">a #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </instance-parameter> + <parameter name="link_" transfer-ownership="none"> + <doc xml:space="preserve">a #GList link that must be part of @queue</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </method> + <function name="new" c:identifier="g_queue_new" introspectable="0"> + <doc xml:space="preserve">Creates a new #GQueue.</doc> + <return-value> + <doc xml:space="preserve">a newly allocated #GQueue</doc> + <type name="Queue" c:type="GQueue*"/> + </return-value> + </function> + </record> + <record name="RWLock" c:type="GRWLock" version="2.32"> + <doc xml:space="preserve">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.</doc> + <field name="p" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="i" readable="0" private="1"> + <array zero-terminated="0" fixed-size="2"> + <type name="guint" c:type="guint"/> + </array> + </field> + <method name="clear" c:identifier="g_rw_lock_clear"> + <doc xml:space="preserve">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</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="rw_lock" transfer-ownership="none"> + <doc xml:space="preserve">an initialized #GRWLock</doc> + <type name="RWLock" c:type="GRWLock*"/> + </instance-parameter> + </parameters> + </method> + <method name="init" c:identifier="g_rw_lock_init" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="rw_lock" transfer-ownership="none"> + <doc xml:space="preserve">an uninitialized #GRWLock</doc> + <type name="RWLock" c:type="GRWLock*"/> + </instance-parameter> + </parameters> + </method> + <method name="reader_lock" c:identifier="g_rw_lock_reader_lock" version="2.32"> + <doc xml:space="preserve">Obtain a read lock on @rw_lock. If another thread currently holds +the write lock on @rw_lock, the current thread will block until the +write lock was (held and) released. 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. + +Calling g_rw_lock_reader_lock() while the current thread already +owns a write lock leads to undefined behaviour. Read locks however +can be taken recursively, in which case you need to make sure to +call g_rw_lock_reader_unlock() the same amount of times. + +It is implementation-defined how many read locks are allowed to be +held on the same lock simultaneously. If the limit is hit, +or if a deadlock is detected, a critical warning will be emitted.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="rw_lock" transfer-ownership="none"> + <doc xml:space="preserve">a #GRWLock</doc> + <type name="RWLock" c:type="GRWLock*"/> + </instance-parameter> + </parameters> + </method> + <method name="reader_trylock" c:identifier="g_rw_lock_reader_trylock" version="2.32"> + <doc xml:space="preserve">Tries to obtain a read lock on @rw_lock and returns %TRUE if +the read lock was successfully obtained. Otherwise it +returns %FALSE.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @rw_lock could be locked</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="rw_lock" transfer-ownership="none"> + <doc xml:space="preserve">a #GRWLock</doc> + <type name="RWLock" c:type="GRWLock*"/> + </instance-parameter> + </parameters> + </method> + <method name="reader_unlock" c:identifier="g_rw_lock_reader_unlock" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="rw_lock" transfer-ownership="none"> + <doc xml:space="preserve">a #GRWLock</doc> + <type name="RWLock" c:type="GRWLock*"/> + </instance-parameter> + </parameters> + </method> + <method name="writer_lock" c:identifier="g_rw_lock_writer_lock" version="2.32"> + <doc xml:space="preserve">Obtain a write lock on @rw_lock. If another thread currently 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. + +Calling g_rw_lock_writer_lock() while the current thread already +owns a read or write lock on @rw_lock leads to undefined behaviour.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="rw_lock" transfer-ownership="none"> + <doc xml:space="preserve">a #GRWLock</doc> + <type name="RWLock" c:type="GRWLock*"/> + </instance-parameter> + </parameters> + </method> + <method name="writer_trylock" c:identifier="g_rw_lock_writer_trylock" version="2.32"> + <doc xml:space="preserve">Tries to obtain a write lock on @rw_lock. If another thread +currently holds a read or write lock on @rw_lock, it immediately +returns %FALSE. +Otherwise it locks @rw_lock and returns %TRUE.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @rw_lock could be locked</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="rw_lock" transfer-ownership="none"> + <doc xml:space="preserve">a #GRWLock</doc> + <type name="RWLock" c:type="GRWLock*"/> + </instance-parameter> + </parameters> + </method> + <method name="writer_unlock" c:identifier="g_rw_lock_writer_unlock" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="rw_lock" transfer-ownership="none"> + <doc xml:space="preserve">a #GRWLock</doc> + <type name="RWLock" c:type="GRWLock*"/> + </instance-parameter> + </parameters> + </method> + </record> + <record name="Rand" c:type="GRand" disguised="1"> + <doc xml:space="preserve">The GRand struct is an opaque data structure. It should only be +accessed through the g_rand_* functions.</doc> + <method name="copy" c:identifier="g_rand_copy" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the new #GRand</doc> + <type name="Rand" c:type="GRand*"/> + </return-value> + <parameters> + <instance-parameter name="rand_" transfer-ownership="none"> + <doc xml:space="preserve">a #GRand</doc> + <type name="Rand" c:type="GRand*"/> + </instance-parameter> + </parameters> + </method> + <method name="double" c:identifier="g_rand_double"> + <doc xml:space="preserve">Returns the next random #gdouble from @rand_ equally distributed over +the range [0..1).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a random number</doc> + <type name="gdouble" c:type="gdouble"/> + </return-value> + <parameters> + <instance-parameter name="rand_" transfer-ownership="none"> + <doc xml:space="preserve">a #GRand</doc> + <type name="Rand" c:type="GRand*"/> + </instance-parameter> + </parameters> + </method> + <method name="double_range" c:identifier="g_rand_double_range"> + <doc xml:space="preserve">Returns the next random #gdouble from @rand_ equally distributed over +the range [@begin..@end).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a random number</doc> + <type name="gdouble" c:type="gdouble"/> + </return-value> + <parameters> + <instance-parameter name="rand_" transfer-ownership="none"> + <doc xml:space="preserve">a #GRand</doc> + <type name="Rand" c:type="GRand*"/> + </instance-parameter> + <parameter name="begin" transfer-ownership="none"> + <doc xml:space="preserve">lower closed bound of the interval</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + <parameter name="end" transfer-ownership="none"> + <doc xml:space="preserve">upper open bound of the interval</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + </parameters> + </method> + <method name="free" c:identifier="g_rand_free"> + <doc xml:space="preserve">Frees the memory allocated for the #GRand.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="rand_" transfer-ownership="none"> + <doc xml:space="preserve">a #GRand</doc> + <type name="Rand" c:type="GRand*"/> + </instance-parameter> + </parameters> + </method> + <method name="int" c:identifier="g_rand_int"> + <doc xml:space="preserve">Returns the next random #guint32 from @rand_ equally distributed over +the range [0..2^32-1].</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a random number</doc> + <type name="guint32" c:type="guint32"/> + </return-value> + <parameters> + <instance-parameter name="rand_" transfer-ownership="none"> + <doc xml:space="preserve">a #GRand</doc> + <type name="Rand" c:type="GRand*"/> + </instance-parameter> + </parameters> + </method> + <method name="int_range" c:identifier="g_rand_int_range"> + <doc xml:space="preserve">Returns the next random #gint32 from @rand_ equally distributed over +the range [@begin..@end-1].</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a random number</doc> + <type name="gint32" c:type="gint32"/> + </return-value> + <parameters> + <instance-parameter name="rand_" transfer-ownership="none"> + <doc xml:space="preserve">a #GRand</doc> + <type name="Rand" c:type="GRand*"/> + </instance-parameter> + <parameter name="begin" transfer-ownership="none"> + <doc xml:space="preserve">lower closed bound of the interval</doc> + <type name="gint32" c:type="gint32"/> + </parameter> + <parameter name="end" transfer-ownership="none"> + <doc xml:space="preserve">upper open bound of the interval</doc> + <type name="gint32" c:type="gint32"/> + </parameter> + </parameters> + </method> + <method name="set_seed" c:identifier="g_rand_set_seed"> + <doc xml:space="preserve">Sets the seed for the random number generator #GRand to @seed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="rand_" transfer-ownership="none"> + <doc xml:space="preserve">a #GRand</doc> + <type name="Rand" c:type="GRand*"/> + </instance-parameter> + <parameter name="seed" transfer-ownership="none"> + <doc xml:space="preserve">a value to reinitialize the random number generator</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + </parameters> + </method> + <method name="set_seed_array" c:identifier="g_rand_set_seed_array" version="2.4"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="rand_" transfer-ownership="none"> + <doc xml:space="preserve">a #GRand</doc> + <type name="Rand" c:type="GRand*"/> + </instance-parameter> + <parameter name="seed" transfer-ownership="none"> + <doc xml:space="preserve">array to initialize with</doc> + <type name="guint32" c:type="const guint32*"/> + </parameter> + <parameter name="seed_length" transfer-ownership="none"> + <doc xml:space="preserve">length of array</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <function name="new" c:identifier="g_rand_new" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value> + <doc xml:space="preserve">the new #GRand</doc> + <type name="Rand" c:type="GRand*"/> + </return-value> + </function> + <function name="new_with_seed" c:identifier="g_rand_new_with_seed" introspectable="0"> + <doc xml:space="preserve">Creates a new random number generator initialized with @seed.</doc> + <return-value> + <doc xml:space="preserve">the new #GRand</doc> + <type name="Rand" c:type="GRand*"/> + </return-value> + <parameters> + <parameter name="seed" transfer-ownership="none"> + <doc xml:space="preserve">a value to initialize the random number generator</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + </parameters> + </function> + <function name="new_with_seed_array" c:identifier="g_rand_new_with_seed_array" version="2.4" introspectable="0"> + <doc xml:space="preserve">Creates a new random number generator initialized with @seed.</doc> + <return-value> + <doc xml:space="preserve">the new #GRand</doc> + <type name="Rand" c:type="GRand*"/> + </return-value> + <parameters> + <parameter name="seed" transfer-ownership="none"> + <doc xml:space="preserve">an array of seeds to initialize the random number generator</doc> + <type name="guint32" c:type="const guint32*"/> + </parameter> + <parameter name="seed_length" transfer-ownership="none"> + <doc xml:space="preserve">an array of seeds to initialize the random number + generator</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + </record> + <record name="RecMutex" c:type="GRecMutex" version="2.32"> + <doc xml:space="preserve">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.</doc> + <field name="p" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="i" readable="0" private="1"> + <array zero-terminated="0" fixed-size="2"> + <type name="guint" c:type="guint"/> + </array> + </field> + <method name="clear" c:identifier="g_rec_mutex_clear"> + <doc xml:space="preserve">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</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="rec_mutex" transfer-ownership="none"> + <doc xml:space="preserve">an initialized #GRecMutex</doc> + <type name="RecMutex" c:type="GRecMutex*"/> + </instance-parameter> + </parameters> + </method> + <method name="init" c:identifier="g_rec_mutex_init" version="2.32"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="rec_mutex" transfer-ownership="none"> + <doc xml:space="preserve">an uninitialized #GRecMutex</doc> + <type name="RecMutex" c:type="GRecMutex*"/> + </instance-parameter> + </parameters> + </method> + <method name="lock" c:identifier="g_rec_mutex_lock" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="rec_mutex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRecMutex</doc> + <type name="RecMutex" c:type="GRecMutex*"/> + </instance-parameter> + </parameters> + </method> + <method name="trylock" c:identifier="g_rec_mutex_trylock" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @rec_mutex could be locked</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="rec_mutex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRecMutex</doc> + <type name="RecMutex" c:type="GRecMutex*"/> + </instance-parameter> + </parameters> + </method> + <method name="unlock" c:identifier="g_rec_mutex_unlock" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="rec_mutex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRecMutex</doc> + <type name="RecMutex" c:type="GRecMutex*"/> + </instance-parameter> + </parameters> + </method> + </record> + <record name="Regex" c:type="GRegex" version="2.14" glib:type-name="GRegex" glib:get-type="g_regex_get_type" c:symbol-prefix="regex"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_regex_new" version="2.14" throws="1"> + <doc xml:space="preserve">Compiles the regular expression to an internal form, and does +the initial setup of the #GRegex structure.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GRegex structure or %NULL if an error occurred. Call + g_regex_unref() when you are done with it</doc> + <type name="Regex" c:type="GRegex*"/> + </return-value> + <parameters> + <parameter name="pattern" transfer-ownership="none"> + <doc xml:space="preserve">the regular expression</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="compile_options" transfer-ownership="none"> + <doc xml:space="preserve">compile options for the regular expression, or 0</doc> + <type name="RegexCompileFlags" c:type="GRegexCompileFlags"/> + </parameter> + <parameter name="match_options" transfer-ownership="none"> + <doc xml:space="preserve">match options for the regular expression, or 0</doc> + <type name="RegexMatchFlags" c:type="GRegexMatchFlags"/> + </parameter> + </parameters> + </constructor> + <method name="get_capture_count" c:identifier="g_regex_get_capture_count" version="2.14"> + <doc xml:space="preserve">Returns the number of capturing subpatterns in the pattern.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of capturing subpatterns</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_compile_flags" c:identifier="g_regex_get_compile_flags" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">flags from #GRegexCompileFlags</doc> + <type name="RegexCompileFlags" c:type="GRegexCompileFlags"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_has_cr_or_lf" c:identifier="g_regex_get_has_cr_or_lf" version="2.34"> + <doc xml:space="preserve">Checks whether the pattern contains explicit CR or LF references.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the pattern contains explicit CR or LF references</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex structure</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_match_flags" c:identifier="g_regex_get_match_flags" version="2.26"> + <doc xml:space="preserve">Returns the match options that @regex was created with.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">flags from #GRegexMatchFlags</doc> + <type name="RegexMatchFlags" c:type="GRegexMatchFlags"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_max_backref" c:identifier="g_regex_get_max_backref" version="2.14"> + <doc xml:space="preserve">Returns the number of the highest back reference +in the pattern, or 0 if the pattern does not contain +back references.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of the highest back reference</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_max_lookbehind" c:identifier="g_regex_get_max_lookbehind" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of characters in the longest lookbehind assertion.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex structure</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_pattern" c:identifier="g_regex_get_pattern" version="2.14"> + <doc xml:space="preserve">Gets the pattern string associated with @regex, i.e. a copy of +the string passed to g_regex_new().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the pattern of @regex</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex structure</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_string_number" c:identifier="g_regex_get_string_number" version="2.14"> + <doc xml:space="preserve">Retrieves the number of the subexpression named @name.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The number of the subexpression or -1 if @name + does not exists</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">#GRegex structure</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">name of the subexpression</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="match" c:identifier="g_regex_match" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE is the string matched, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex structure from g_regex_new()</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to scan for matches</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="match_options" transfer-ownership="none"> + <doc xml:space="preserve">match options</doc> + <type name="RegexMatchFlags" c:type="GRegexMatchFlags"/> + </parameter> + <parameter name="match_info" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">pointer to location where to store + the #GMatchInfo, or %NULL if you do not need it</doc> + <type name="MatchInfo" c:type="GMatchInfo**"/> + </parameter> + </parameters> + </method> + <method name="match_all" c:identifier="g_regex_match_all" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE is the string matched, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex structure from g_regex_new()</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to scan for matches</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="match_options" transfer-ownership="none"> + <doc xml:space="preserve">match options</doc> + <type name="RegexMatchFlags" c:type="GRegexMatchFlags"/> + </parameter> + <parameter name="match_info" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">pointer to location where to store + the #GMatchInfo, or %NULL if you do not need it</doc> + <type name="MatchInfo" c:type="GMatchInfo**"/> + </parameter> + </parameters> + </method> + <method name="match_all_full" c:identifier="g_regex_match_all_full" version="2.14" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE is the string matched, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex structure from g_regex_new()</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to scan for matches</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="utf8" c:type="gchar"/> + </array> + </parameter> + <parameter name="string_len" transfer-ownership="none"> + <doc xml:space="preserve">the length of @string, in bytes, or -1 if @string is nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="start_position" transfer-ownership="none"> + <doc xml:space="preserve">starting index of the string to match, in bytes</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="match_options" transfer-ownership="none"> + <doc xml:space="preserve">match options</doc> + <type name="RegexMatchFlags" c:type="GRegexMatchFlags"/> + </parameter> + <parameter name="match_info" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">pointer to location where to store + the #GMatchInfo, or %NULL if you do not need it</doc> + <type name="MatchInfo" c:type="GMatchInfo**"/> + </parameter> + </parameters> + </method> + <method name="match_full" c:identifier="g_regex_match_full" version="2.14" throws="1"> + <doc xml:space="preserve">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); + } +} +]|</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE is the string matched, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex structure from g_regex_new()</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to scan for matches</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="utf8" c:type="gchar"/> + </array> + </parameter> + <parameter name="string_len" transfer-ownership="none"> + <doc xml:space="preserve">the length of @string, in bytes, or -1 if @string is nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="start_position" transfer-ownership="none"> + <doc xml:space="preserve">starting index of the string to match, in bytes</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="match_options" transfer-ownership="none"> + <doc xml:space="preserve">match options</doc> + <type name="RegexMatchFlags" c:type="GRegexMatchFlags"/> + </parameter> + <parameter name="match_info" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">pointer to location where to store + the #GMatchInfo, or %NULL if you do not need it</doc> + <type name="MatchInfo" c:type="GMatchInfo**"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_regex_ref" version="2.14"> + <doc xml:space="preserve">Increases reference count of @regex by 1.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">@regex</doc> + <type name="Regex" c:type="GRegex*"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex</doc> + <type name="Regex" c:type="GRegex*"/> + </instance-parameter> + </parameters> + </method> + <method name="replace" c:identifier="g_regex_replace" version="2.14" throws="1"> + <doc xml:space="preserve">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 strings +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".</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string containing the replacements</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex structure</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to perform matches against</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="utf8" c:type="gchar"/> + </array> + </parameter> + <parameter name="string_len" transfer-ownership="none"> + <doc xml:space="preserve">the length of @string, in bytes, or -1 if @string is nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="start_position" transfer-ownership="none"> + <doc xml:space="preserve">starting index of the string to match, in bytes</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="replacement" transfer-ownership="none"> + <doc xml:space="preserve">text to replace each match with</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="match_options" transfer-ownership="none"> + <doc xml:space="preserve">options for the match</doc> + <type name="RegexMatchFlags" c:type="GRegexMatchFlags"/> + </parameter> + </parameters> + </method> + <method name="replace_eval" c:identifier="g_regex_replace_eval" version="2.14" introspectable="0" throws="1"> + <doc xml:space="preserve">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); + +... +]|</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string containing the replacements</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex structure from g_regex_new()</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">string to perform matches against</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="utf8" c:type="gchar"/> + </array> + </parameter> + <parameter name="string_len" transfer-ownership="none"> + <doc xml:space="preserve">the length of @string, in bytes, or -1 if @string is nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="start_position" transfer-ownership="none"> + <doc xml:space="preserve">starting index of the string to match, in bytes</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="match_options" transfer-ownership="none"> + <doc xml:space="preserve">options for the match</doc> + <type name="RegexMatchFlags" c:type="GRegexMatchFlags"/> + </parameter> + <parameter name="eval" transfer-ownership="none" closure="5"> + <doc xml:space="preserve">a function to call for each match</doc> + <type name="RegexEvalCallback" c:type="GRegexEvalCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to the function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="replace_literal" c:identifier="g_regex_replace_literal" version="2.14" throws="1"> + <doc xml:space="preserve">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".</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string containing the replacements</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex structure</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to perform matches against</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="utf8" c:type="gchar"/> + </array> + </parameter> + <parameter name="string_len" transfer-ownership="none"> + <doc xml:space="preserve">the length of @string, in bytes, or -1 if @string is nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="start_position" transfer-ownership="none"> + <doc xml:space="preserve">starting index of the string to match, in bytes</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="replacement" transfer-ownership="none"> + <doc xml:space="preserve">text to replace each match with</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="match_options" transfer-ownership="none"> + <doc xml:space="preserve">options for the match</doc> + <type name="RegexMatchFlags" c:type="GRegexMatchFlags"/> + </parameter> + </parameters> + </method> + <method name="split" c:identifier="g_regex_split" version="2.14"> + <doc xml:space="preserve">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".</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated gchar ** array. Free +it using g_strfreev()</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex structure</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to split with the pattern</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="match_options" transfer-ownership="none"> + <doc xml:space="preserve">match time option flags</doc> + <type name="RegexMatchFlags" c:type="GRegexMatchFlags"/> + </parameter> + </parameters> + </method> + <method name="split_full" c:identifier="g_regex_split_full" version="2.14" throws="1"> + <doc xml:space="preserve">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".</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated gchar ** array. Free +it using g_strfreev()</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex structure</doc> + <type name="Regex" c:type="const GRegex*"/> + </instance-parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to split with the pattern</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="utf8" c:type="gchar"/> + </array> + </parameter> + <parameter name="string_len" transfer-ownership="none"> + <doc xml:space="preserve">the length of @string, in bytes, or -1 if @string is nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="start_position" transfer-ownership="none"> + <doc xml:space="preserve">starting index of the string to match, in bytes</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="match_options" transfer-ownership="none"> + <doc xml:space="preserve">match time option flags</doc> + <type name="RegexMatchFlags" c:type="GRegexMatchFlags"/> + </parameter> + <parameter name="max_tokens" transfer-ownership="none"> + <doc xml:space="preserve">the maximum number of tokens to split @string into. + If this is less than 1, the string is split completely</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_regex_unref" version="2.14"> + <doc xml:space="preserve">Decreases reference count of @regex by 1. When reference count drops +to zero, it frees all the memory associated with the regex structure.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="regex" transfer-ownership="none"> + <doc xml:space="preserve">a #GRegex</doc> + <type name="Regex" c:type="GRegex*"/> + </instance-parameter> + </parameters> + </method> + <function name="check_replacement" c:identifier="g_regex_check_replacement" version="2.14" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether @replacement is a valid replacement string</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="replacement" transfer-ownership="none"> + <doc xml:space="preserve">the replacement string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="has_references" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store information about + references in @replacement or %NULL</doc> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + </parameters> + </function> + <function name="error_quark" c:identifier="g_regex_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="escape_nul" c:identifier="g_regex_escape_nul" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated escaped string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to escape</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @string</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="escape_string" c:identifier="g_regex_escape_string" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated escaped string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to escape</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="utf8" c:type="gchar"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @string, in bytes, or -1 if @string is nul-terminated</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="match_simple" c:identifier="g_regex_match_simple" version="2.14"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the string matched, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="pattern" transfer-ownership="none"> + <doc xml:space="preserve">the regular expression</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to scan for matches</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="compile_options" transfer-ownership="none"> + <doc xml:space="preserve">compile options for the regular expression, or 0</doc> + <type name="RegexCompileFlags" c:type="GRegexCompileFlags"/> + </parameter> + <parameter name="match_options" transfer-ownership="none"> + <doc xml:space="preserve">match options, or 0</doc> + <type name="RegexMatchFlags" c:type="GRegexMatchFlags"/> + </parameter> + </parameters> + </function> + <function name="split_simple" c:identifier="g_regex_split_simple" version="2.14"> + <doc xml:space="preserve">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".</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated array of strings. Free +it using g_strfreev()</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="pattern" transfer-ownership="none"> + <doc xml:space="preserve">the regular expression</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to scan for matches</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="compile_options" transfer-ownership="none"> + <doc xml:space="preserve">compile options for the regular expression, or 0</doc> + <type name="RegexCompileFlags" c:type="GRegexCompileFlags"/> + </parameter> + <parameter name="match_options" transfer-ownership="none"> + <doc xml:space="preserve">match options, or 0</doc> + <type name="RegexMatchFlags" c:type="GRegexMatchFlags"/> + </parameter> + </parameters> + </function> + </record> + <bitfield name="RegexCompileFlags" version="2.14" c:type="GRegexCompileFlags"> + <doc xml:space="preserve">Flags specifying compile-time options.</doc> + <member name="caseless" value="1" c:identifier="G_REGEX_CASELESS"> + <doc xml:space="preserve">Letters in the pattern match both upper- and + lowercase letters. This option can be changed within a pattern + by a "(?i)" option setting.</doc> + </member> + <member name="multiline" value="2" c:identifier="G_REGEX_MULTILINE"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="dotall" value="4" c:identifier="G_REGEX_DOTALL"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="extended" value="8" c:identifier="G_REGEX_EXTENDED"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="anchored" value="16" c:identifier="G_REGEX_ANCHORED"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="dollar_endonly" value="32" c:identifier="G_REGEX_DOLLAR_ENDONLY"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="ungreedy" value="512" c:identifier="G_REGEX_UNGREEDY"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="raw" value="2048" c:identifier="G_REGEX_RAW"> + <doc xml:space="preserve">Usually strings must be valid UTF-8 strings, using this + flag they are considered as a raw sequence of bytes.</doc> + </member> + <member name="no_auto_capture" value="4096" c:identifier="G_REGEX_NO_AUTO_CAPTURE"> + <doc xml:space="preserve">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).</doc> + </member> + <member name="optimize" value="8192" c:identifier="G_REGEX_OPTIMIZE"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="firstline" value="262144" c:identifier="G_REGEX_FIRSTLINE"> + <doc xml:space="preserve">Limits an unanchored pattern to match before (or at) the + first newline. Since: 2.34</doc> + </member> + <member name="dupnames" value="524288" c:identifier="G_REGEX_DUPNAMES"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="newline_cr" value="1048576" c:identifier="G_REGEX_NEWLINE_CR"> + <doc xml:space="preserve">Usually any newline character or character sequence is + recognized. If this option is set, the only recognized newline character + is '\r'.</doc> + </member> + <member name="newline_lf" value="2097152" c:identifier="G_REGEX_NEWLINE_LF"> + <doc xml:space="preserve">Usually any newline character or character sequence is + recognized. If this option is set, the only recognized newline character + is '\n'.</doc> + </member> + <member name="newline_crlf" value="3145728" c:identifier="G_REGEX_NEWLINE_CRLF"> + <doc xml:space="preserve">Usually any newline character or character sequence is + recognized. If this option is set, the only recognized newline character + sequence is '\r\n'.</doc> + </member> + <member name="newline_anycrlf" value="5242880" c:identifier="G_REGEX_NEWLINE_ANYCRLF"> + <doc xml:space="preserve">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</doc> + </member> + <member name="bsr_anycrlf" value="8388608" c:identifier="G_REGEX_BSR_ANYCRLF"> + <doc xml:space="preserve">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</doc> + </member> + <member name="javascript_compat" value="33554432" c:identifier="G_REGEX_JAVASCRIPT_COMPAT"> + <doc xml:space="preserve">Changes behaviour so that it is compatible with + JavaScript rather than PCRE. Since: 2.34</doc> + </member> + </bitfield> + <enumeration name="RegexError" version="2.14" c:type="GRegexError" glib:error-domain="g-regex-error-quark"> + <doc xml:space="preserve">Error codes returned by regular expressions functions.</doc> + <member name="compile" value="0" c:identifier="G_REGEX_ERROR_COMPILE"> + <doc xml:space="preserve">Compilation of the regular expression failed.</doc> + </member> + <member name="optimize" value="1" c:identifier="G_REGEX_ERROR_OPTIMIZE"> + <doc xml:space="preserve">Optimization of the regular expression failed.</doc> + </member> + <member name="replace" value="2" c:identifier="G_REGEX_ERROR_REPLACE"> + <doc xml:space="preserve">Replacement failed due to an ill-formed replacement + string.</doc> + </member> + <member name="match" value="3" c:identifier="G_REGEX_ERROR_MATCH"> + <doc xml:space="preserve">The match process failed.</doc> + </member> + <member name="internal" value="4" c:identifier="G_REGEX_ERROR_INTERNAL"> + <doc xml:space="preserve">Internal error of the regular expression engine. + Since 2.16</doc> + </member> + <member name="stray_backslash" value="101" c:identifier="G_REGEX_ERROR_STRAY_BACKSLASH"> + <doc xml:space="preserve">"\\" at end of pattern. Since 2.16</doc> + </member> + <member name="missing_control_char" value="102" c:identifier="G_REGEX_ERROR_MISSING_CONTROL_CHAR"> + <doc xml:space="preserve">"\\c" at end of pattern. Since 2.16</doc> + </member> + <member name="unrecognized_escape" value="103" c:identifier="G_REGEX_ERROR_UNRECOGNIZED_ESCAPE"> + <doc xml:space="preserve">Unrecognized character follows "\\". + Since 2.16</doc> + </member> + <member name="quantifiers_out_of_order" value="104" c:identifier="G_REGEX_ERROR_QUANTIFIERS_OUT_OF_ORDER"> + <doc xml:space="preserve">Numbers out of order in "{}" + quantifier. Since 2.16</doc> + </member> + <member name="quantifier_too_big" value="105" c:identifier="G_REGEX_ERROR_QUANTIFIER_TOO_BIG"> + <doc xml:space="preserve">Number too big in "{}" quantifier. + Since 2.16</doc> + </member> + <member name="unterminated_character_class" value="106" c:identifier="G_REGEX_ERROR_UNTERMINATED_CHARACTER_CLASS"> + <doc xml:space="preserve">Missing terminating "]" for + character class. Since 2.16</doc> + </member> + <member name="invalid_escape_in_character_class" value="107" c:identifier="G_REGEX_ERROR_INVALID_ESCAPE_IN_CHARACTER_CLASS"> + <doc xml:space="preserve">Invalid escape sequence + in character class. Since 2.16</doc> + </member> + <member name="range_out_of_order" value="108" c:identifier="G_REGEX_ERROR_RANGE_OUT_OF_ORDER"> + <doc xml:space="preserve">Range out of order in character class. + Since 2.16</doc> + </member> + <member name="nothing_to_repeat" value="109" c:identifier="G_REGEX_ERROR_NOTHING_TO_REPEAT"> + <doc xml:space="preserve">Nothing to repeat. Since 2.16</doc> + </member> + <member name="unrecognized_character" value="112" c:identifier="G_REGEX_ERROR_UNRECOGNIZED_CHARACTER"> + <doc xml:space="preserve">Unrecognized character after "(?", + "(?<" or "(?P". Since 2.16</doc> + </member> + <member name="posix_named_class_outside_class" value="113" c:identifier="G_REGEX_ERROR_POSIX_NAMED_CLASS_OUTSIDE_CLASS"> + <doc xml:space="preserve">POSIX named classes are + supported only within a class. Since 2.16</doc> + </member> + <member name="unmatched_parenthesis" value="114" c:identifier="G_REGEX_ERROR_UNMATCHED_PARENTHESIS"> + <doc xml:space="preserve">Missing terminating ")" or ")" + without opening "(". Since 2.16</doc> + </member> + <member name="inexistent_subpattern_reference" value="115" c:identifier="G_REGEX_ERROR_INEXISTENT_SUBPATTERN_REFERENCE"> + <doc xml:space="preserve">Reference to non-existent + subpattern. Since 2.16</doc> + </member> + <member name="unterminated_comment" value="118" c:identifier="G_REGEX_ERROR_UNTERMINATED_COMMENT"> + <doc xml:space="preserve">Missing terminating ")" after comment. + Since 2.16</doc> + </member> + <member name="expression_too_large" value="120" c:identifier="G_REGEX_ERROR_EXPRESSION_TOO_LARGE"> + <doc xml:space="preserve">Regular expression too large. + Since 2.16</doc> + </member> + <member name="memory_error" value="121" c:identifier="G_REGEX_ERROR_MEMORY_ERROR"> + <doc xml:space="preserve">Failed to get memory. Since 2.16</doc> + </member> + <member name="variable_length_lookbehind" value="125" c:identifier="G_REGEX_ERROR_VARIABLE_LENGTH_LOOKBEHIND"> + <doc xml:space="preserve">Lookbehind assertion is not + fixed length. Since 2.16</doc> + </member> + <member name="malformed_condition" value="126" c:identifier="G_REGEX_ERROR_MALFORMED_CONDITION"> + <doc xml:space="preserve">Malformed number or name after "(?(". + Since 2.16</doc> + </member> + <member name="too_many_conditional_branches" value="127" c:identifier="G_REGEX_ERROR_TOO_MANY_CONDITIONAL_BRANCHES"> + <doc xml:space="preserve">Conditional group contains + more than two branches. Since 2.16</doc> + </member> + <member name="assertion_expected" value="128" c:identifier="G_REGEX_ERROR_ASSERTION_EXPECTED"> + <doc xml:space="preserve">Assertion expected after "(?(". + Since 2.16</doc> + </member> + <member name="unknown_posix_class_name" value="130" c:identifier="G_REGEX_ERROR_UNKNOWN_POSIX_CLASS_NAME"> + <doc xml:space="preserve">Unknown POSIX class name. + Since 2.16</doc> + </member> + <member name="posix_collating_elements_not_supported" value="131" c:identifier="G_REGEX_ERROR_POSIX_COLLATING_ELEMENTS_NOT_SUPPORTED"> + <doc xml:space="preserve">POSIX collating + elements are not supported. Since 2.16</doc> + </member> + <member name="hex_code_too_large" value="134" c:identifier="G_REGEX_ERROR_HEX_CODE_TOO_LARGE"> + <doc xml:space="preserve">Character value in "\\x{...}" sequence + is too large. Since 2.16</doc> + </member> + <member name="invalid_condition" value="135" c:identifier="G_REGEX_ERROR_INVALID_CONDITION"> + <doc xml:space="preserve">Invalid condition "(?(0)". Since 2.16</doc> + </member> + <member name="single_byte_match_in_lookbehind" value="136" c:identifier="G_REGEX_ERROR_SINGLE_BYTE_MATCH_IN_LOOKBEHIND"> + <doc xml:space="preserve">\\C not allowed in + lookbehind assertion. Since 2.16</doc> + </member> + <member name="infinite_loop" value="140" c:identifier="G_REGEX_ERROR_INFINITE_LOOP"> + <doc xml:space="preserve">Recursive call could loop indefinitely. + Since 2.16</doc> + </member> + <member name="missing_subpattern_name_terminator" value="142" c:identifier="G_REGEX_ERROR_MISSING_SUBPATTERN_NAME_TERMINATOR"> + <doc xml:space="preserve">Missing terminator + in subpattern name. Since 2.16</doc> + </member> + <member name="duplicate_subpattern_name" value="143" c:identifier="G_REGEX_ERROR_DUPLICATE_SUBPATTERN_NAME"> + <doc xml:space="preserve">Two named subpatterns have + the same name. Since 2.16</doc> + </member> + <member name="malformed_property" value="146" c:identifier="G_REGEX_ERROR_MALFORMED_PROPERTY"> + <doc xml:space="preserve">Malformed "\\P" or "\\p" sequence. + Since 2.16</doc> + </member> + <member name="unknown_property" value="147" c:identifier="G_REGEX_ERROR_UNKNOWN_PROPERTY"> + <doc xml:space="preserve">Unknown property name after "\\P" or + "\\p". Since 2.16</doc> + </member> + <member name="subpattern_name_too_long" value="148" c:identifier="G_REGEX_ERROR_SUBPATTERN_NAME_TOO_LONG"> + <doc xml:space="preserve">Subpattern name is too long + (maximum 32 characters). Since 2.16</doc> + </member> + <member name="too_many_subpatterns" value="149" c:identifier="G_REGEX_ERROR_TOO_MANY_SUBPATTERNS"> + <doc xml:space="preserve">Too many named subpatterns (maximum + 10,000). Since 2.16</doc> + </member> + <member name="invalid_octal_value" value="151" c:identifier="G_REGEX_ERROR_INVALID_OCTAL_VALUE"> + <doc xml:space="preserve">Octal value is greater than "\\377". + Since 2.16</doc> + </member> + <member name="too_many_branches_in_define" value="154" c:identifier="G_REGEX_ERROR_TOO_MANY_BRANCHES_IN_DEFINE"> + <doc xml:space="preserve">"DEFINE" group contains more + than one branch. Since 2.16</doc> + </member> + <member name="define_repetion" value="155" c:identifier="G_REGEX_ERROR_DEFINE_REPETION"> + <doc xml:space="preserve">Repeating a "DEFINE" group is not allowed. + This error is never raised. Since: 2.16 Deprecated: 2.34</doc> + </member> + <member name="inconsistent_newline_options" value="156" c:identifier="G_REGEX_ERROR_INCONSISTENT_NEWLINE_OPTIONS"> + <doc xml:space="preserve">Inconsistent newline options. + Since 2.16</doc> + </member> + <member name="missing_back_reference" value="157" c:identifier="G_REGEX_ERROR_MISSING_BACK_REFERENCE"> + <doc xml:space="preserve">"\\g" is not followed by a braced, + angle-bracketed, or quoted name or number, or by a plain number. Since: 2.16</doc> + </member> + <member name="invalid_relative_reference" value="158" c:identifier="G_REGEX_ERROR_INVALID_RELATIVE_REFERENCE"> + <doc xml:space="preserve">relative reference must not be zero. Since: 2.34</doc> + </member> + <member name="backtracking_control_verb_argument_forbidden" value="159" c:identifier="G_REGEX_ERROR_BACKTRACKING_CONTROL_VERB_ARGUMENT_FORBIDDEN"> + <doc xml:space="preserve">the backtracing + control verb used does not allow an argument. Since: 2.34</doc> + </member> + <member name="unknown_backtracking_control_verb" value="160" c:identifier="G_REGEX_ERROR_UNKNOWN_BACKTRACKING_CONTROL_VERB"> + <doc xml:space="preserve">unknown backtracing + control verb. Since: 2.34</doc> + </member> + <member name="number_too_big" value="161" c:identifier="G_REGEX_ERROR_NUMBER_TOO_BIG"> + <doc xml:space="preserve">number is too big in escape sequence. Since: 2.34</doc> + </member> + <member name="missing_subpattern_name" value="162" c:identifier="G_REGEX_ERROR_MISSING_SUBPATTERN_NAME"> + <doc xml:space="preserve">Missing subpattern name. Since: 2.34</doc> + </member> + <member name="missing_digit" value="163" c:identifier="G_REGEX_ERROR_MISSING_DIGIT"> + <doc xml:space="preserve">Missing digit. Since 2.34</doc> + </member> + <member name="invalid_data_character" value="164" c:identifier="G_REGEX_ERROR_INVALID_DATA_CHARACTER"> + <doc xml:space="preserve">In JavaScript compatibility mode, + "[" is an invalid data character. Since: 2.34</doc> + </member> + <member name="extra_subpattern_name" value="165" c:identifier="G_REGEX_ERROR_EXTRA_SUBPATTERN_NAME"> + <doc xml:space="preserve">different names for subpatterns of the + same number are not allowed. Since: 2.34</doc> + </member> + <member name="backtracking_control_verb_argument_required" value="166" c:identifier="G_REGEX_ERROR_BACKTRACKING_CONTROL_VERB_ARGUMENT_REQUIRED"> + <doc xml:space="preserve">the backtracing control + verb requires an argument. Since: 2.34</doc> + </member> + <member name="invalid_control_char" value="168" c:identifier="G_REGEX_ERROR_INVALID_CONTROL_CHAR"> + <doc xml:space="preserve">"\\c" must be followed by an ASCII + character. Since: 2.34</doc> + </member> + <member name="missing_name" value="169" c:identifier="G_REGEX_ERROR_MISSING_NAME"> + <doc xml:space="preserve">"\\k" is not followed by a braced, angle-bracketed, or + quoted name. Since: 2.34</doc> + </member> + <member name="not_supported_in_class" value="171" c:identifier="G_REGEX_ERROR_NOT_SUPPORTED_IN_CLASS"> + <doc xml:space="preserve">"\\N" is not supported in a class. Since: 2.34</doc> + </member> + <member name="too_many_forward_references" value="172" c:identifier="G_REGEX_ERROR_TOO_MANY_FORWARD_REFERENCES"> + <doc xml:space="preserve">too many forward references. Since: 2.34</doc> + </member> + <member name="name_too_long" value="175" c:identifier="G_REGEX_ERROR_NAME_TOO_LONG"> + <doc xml:space="preserve">the name is too long in "(*MARK)", "(*PRUNE)", + "(*SKIP)", or "(*THEN)". Since: 2.34</doc> + </member> + <member name="character_value_too_large" value="176" c:identifier="G_REGEX_ERROR_CHARACTER_VALUE_TOO_LARGE"> + <doc xml:space="preserve">the character value in the \\u sequence is + too large. Since: 2.34</doc> + </member> + </enumeration> + <callback name="RegexEvalCallback" c:type="GRegexEvalCallback" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%FALSE to continue the replacement process, %TRUE to stop it</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="match_info" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="MatchInfo" c:type="const GMatchInfo*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GString containing the new string</doc> + <type name="String" c:type="GString*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">user data passed to g_regex_replace_eval()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <bitfield name="RegexMatchFlags" version="2.14" c:type="GRegexMatchFlags"> + <doc xml:space="preserve">Flags specifying match-time options.</doc> + <member name="anchored" value="16" c:identifier="G_REGEX_MATCH_ANCHORED"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="notbol" value="128" c:identifier="G_REGEX_MATCH_NOTBOL"> + <doc xml:space="preserve">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".</doc> + </member> + <member name="noteol" value="256" c:identifier="G_REGEX_MATCH_NOTEOL"> + <doc xml:space="preserve">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".</doc> + </member> + <member name="notempty" value="1024" c:identifier="G_REGEX_MATCH_NOTEMPTY"> + <doc xml:space="preserve">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".</doc> + </member> + <member name="partial" value="32768" c:identifier="G_REGEX_MATCH_PARTIAL"> + <doc xml:space="preserve">Turns on the partial matching feature, for more + documentation on partial matching see g_match_info_is_partial_match().</doc> + </member> + <member name="newline_cr" value="1048576" c:identifier="G_REGEX_MATCH_NEWLINE_CR"> + <doc xml:space="preserve">Overrides the newline definition set when + creating a new #GRegex, setting the '\r' character as line terminator.</doc> + </member> + <member name="newline_lf" value="2097152" c:identifier="G_REGEX_MATCH_NEWLINE_LF"> + <doc xml:space="preserve">Overrides the newline definition set when + creating a new #GRegex, setting the '\n' character as line terminator.</doc> + </member> + <member name="newline_crlf" value="3145728" c:identifier="G_REGEX_MATCH_NEWLINE_CRLF"> + <doc xml:space="preserve">Overrides the newline definition set when + creating a new #GRegex, setting the '\r\n' characters sequence as line terminator.</doc> + </member> + <member name="newline_any" value="4194304" c:identifier="G_REGEX_MATCH_NEWLINE_ANY"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="newline_anycrlf" value="5242880" c:identifier="G_REGEX_MATCH_NEWLINE_ANYCRLF"> + <doc xml:space="preserve">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</doc> + </member> + <member name="bsr_anycrlf" value="8388608" c:identifier="G_REGEX_MATCH_BSR_ANYCRLF"> + <doc xml:space="preserve">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</doc> + </member> + <member name="bsr_any" value="16777216" c:identifier="G_REGEX_MATCH_BSR_ANY"> + <doc xml:space="preserve">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</doc> + </member> + <member name="partial_soft" value="32768" c:identifier="G_REGEX_MATCH_PARTIAL_SOFT"> + <doc xml:space="preserve">An alias for #G_REGEX_MATCH_PARTIAL. Since: 2.34</doc> + </member> + <member name="partial_hard" value="134217728" c:identifier="G_REGEX_MATCH_PARTIAL_HARD"> + <doc xml:space="preserve">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</doc> + </member> + <member name="notempty_atstart" value="268435456" c:identifier="G_REGEX_MATCH_NOTEMPTY_ATSTART"> + <doc xml:space="preserve">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</doc> + </member> + </bitfield> + <constant name="SEARCHPATH_SEPARATOR" value="58" c:type="G_SEARCHPATH_SEPARATOR"> + <doc xml:space="preserve">The search path separator character. +This is ':' on UNIX machines and ';' under Windows.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="SEARCHPATH_SEPARATOR_S" value=":" c:type="G_SEARCHPATH_SEPARATOR_S"> + <doc xml:space="preserve">The search path separator as a string. +This is ":" on UNIX machines and ";" under Windows.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="SIZEOF_LONG" value="8" c:type="GLIB_SIZEOF_LONG"> + <type name="gint" c:type="gint"/> + </constant> + <function-macro name="SIZEOF_MEMBER" c:identifier="G_SIZEOF_MEMBER" version="2.64" introspectable="0"> + <doc xml:space="preserve">Returns the size of @member in the struct definition without having a +declared instance of @struct_type.</doc> + <parameters> + <parameter name="struct_type"> + <doc xml:space="preserve">a structure type, e.g. #GOutputVector</doc> + </parameter> + <parameter name="member"> + <doc xml:space="preserve">a field in the structure, e.g. `size`</doc> + </parameter> + </parameters> + </function-macro> + <constant name="SIZEOF_SIZE_T" value="8" c:type="GLIB_SIZEOF_SIZE_T"> + <type name="gint" c:type="gint"/> + </constant> + <constant name="SIZEOF_SSIZE_T" value="8" c:type="GLIB_SIZEOF_SSIZE_T"> + <type name="gint" c:type="gint"/> + </constant> + <constant name="SIZEOF_VOID_P" value="8" c:type="GLIB_SIZEOF_VOID_P"> + <type name="gint" c:type="gint"/> + </constant> + <record name="SList" c:type="GSList"> + <doc xml:space="preserve">The #GSList struct is used for each element in the singly-linked +list.</doc> + <field name="data" writable="1"> + <doc xml:space="preserve">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]</doc> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="next" writable="1"> + <doc xml:space="preserve">contains the link to the next element in the list.</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </field> + <function name="alloc" c:identifier="g_slist_alloc" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">a pointer to the newly-allocated #GSList element.</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + </function> + <function name="append" c:identifier="g_slist_append" introspectable="0"> + <doc xml:space="preserve">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)); +]|</doc> + <return-value> + <doc xml:space="preserve">the new start of the #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new element</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="concat" c:identifier="g_slist_concat" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the start of the new #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list1" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="list2" transfer-ownership="none"> + <doc xml:space="preserve">the #GSList to add to the end of the first #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="copy" c:identifier="g_slist_copy" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">a copy of @list</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="copy_deep" c:identifier="g_slist_copy_deep" version="2.34" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <return-value> + <doc xml:space="preserve">a full copy of @list, use g_slist_free_full() to free it</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">a copy function used to copy every element in the list</doc> + <type name="CopyFunc" c:type="GCopyFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to the copy function @func, or #NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="delete_link" c:identifier="g_slist_delete_link" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the new head of @list</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="link_" transfer-ownership="none"> + <doc xml:space="preserve">node to delete</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="find" c:identifier="g_slist_find" introspectable="0"> + <doc xml:space="preserve">Finds the element in a #GSList which +contains the given data.</doc> + <return-value> + <doc xml:space="preserve">the found #GSList element, + or %NULL if it is not found</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the element data to find</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="find_custom" c:identifier="g_slist_find_custom" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the found #GSList element, or %NULL if it is not found</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to the function</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="func" transfer-ownership="none"> + <doc xml:space="preserve">the function to call for each element. + It should return 0 when the desired element is found</doc> + <type name="CompareFunc" c:type="GCompareFunc"/> + </parameter> + </parameters> + </function> + <function name="foreach" c:identifier="g_slist_foreach" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function to call with each element's data</doc> + <type name="Func" c:type="GFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to the function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="free" c:identifier="g_slist_free" introspectable="0"> + <doc xml:space="preserve">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)); +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">the first link of a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="free_1" c:identifier="g_slist_free_1" introspectable="0"> + <doc xml:space="preserve">Frees one #GSList element. +It is usually used after g_slist_remove_link().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList element</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="free_full" c:identifier="g_slist_free_full" version="2.28" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">the first link of a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="free_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">the function to be called to free each element's data</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="index" c:identifier="g_slist_index" introspectable="0"> + <doc xml:space="preserve">Gets the position of the element containing +the given data (starting from 0).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the index of the element containing the data, + or -1 if the data is not found</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to find</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="insert" c:identifier="g_slist_insert" introspectable="0"> + <doc xml:space="preserve">Inserts a new element into the list at the given position.</doc> + <return-value> + <doc xml:space="preserve">the new start of the #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new element</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="insert_before" c:identifier="g_slist_insert_before" introspectable="0"> + <doc xml:space="preserve">Inserts a node before @sibling containing @data.</doc> + <return-value> + <doc xml:space="preserve">the new head of the list.</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="slist" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="sibling" transfer-ownership="none"> + <doc xml:space="preserve">node to insert @data before</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to put in the newly-inserted node</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="insert_sorted" c:identifier="g_slist_insert_sorted" introspectable="0"> + <doc xml:space="preserve">Inserts a new element into the list, using the given +comparison function to determine its position.</doc> + <return-value> + <doc xml:space="preserve">the new start of the #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new element</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="func" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="CompareFunc" c:type="GCompareFunc"/> + </parameter> + </parameters> + </function> + <function name="insert_sorted_with_data" c:identifier="g_slist_insert_sorted_with_data" version="2.10" introspectable="0"> + <doc xml:space="preserve">Inserts a new element into the list, using the given +comparison function to determine its position.</doc> + <return-value> + <doc xml:space="preserve">the new start of the #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new element</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="func" transfer-ownership="none" closure="3"> + <doc xml:space="preserve">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.</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to comparison function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="last" c:identifier="g_slist_last" introspectable="0"> + <doc xml:space="preserve">Gets the last element in a #GSList. + +This function iterates over the whole list.</doc> + <return-value> + <doc xml:space="preserve">the last element in the #GSList, + or %NULL if the #GSList has no elements</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="length" c:identifier="g_slist_length" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of elements in the #GSList</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="nth" c:identifier="g_slist_nth" introspectable="0"> + <doc xml:space="preserve">Gets the element at the given position in a #GSList.</doc> + <return-value> + <doc xml:space="preserve">the element, or %NULL if the position is off + the end of the #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">the position of the element, counting from 0</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="nth_data" c:identifier="g_slist_nth_data" introspectable="0"> + <doc xml:space="preserve">Gets the data of the element at the given position.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the element's data, or %NULL if the position + is off the end of the #GSList</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">the position of the element</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="position" c:identifier="g_slist_position" introspectable="0"> + <doc xml:space="preserve">Gets the position of the given element +in the #GSList (starting from 0).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the position of the element in the #GSList, + or -1 if the element is not found</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="llink" transfer-ownership="none"> + <doc xml:space="preserve">an element in the #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="prepend" c:identifier="g_slist_prepend" introspectable="0"> + <doc xml:space="preserve">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"); +]|</doc> + <return-value> + <doc xml:space="preserve">the new start of the #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new element</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="remove" c:identifier="g_slist_remove" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the new start of the #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data of the element to remove</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="remove_all" c:identifier="g_slist_remove_all" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">new head of @list</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to remove</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="remove_link" c:identifier="g_slist_remove_link" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the new start of the #GSList, without the element</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="link_" transfer-ownership="none"> + <doc xml:space="preserve">an element in the #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="reverse" c:identifier="g_slist_reverse" introspectable="0"> + <doc xml:space="preserve">Reverses a #GSList.</doc> + <return-value> + <doc xml:space="preserve">the start of the reversed #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="sort" c:identifier="g_slist_sort" introspectable="0"> + <doc xml:space="preserve">Sorts a #GSList using the given comparison function. The algorithm +used is a stable sort.</doc> + <return-value> + <doc xml:space="preserve">the start of the sorted #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="compare_func" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="CompareFunc" c:type="GCompareFunc"/> + </parameter> + </parameters> + </function> + <function name="sort_with_data" c:identifier="g_slist_sort_with_data" introspectable="0"> + <doc xml:space="preserve">Like g_slist_sort(), but the sort function accepts a user data argument.</doc> + <return-value> + <doc xml:space="preserve">new head of the list</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList</doc> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="compare_func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">comparison function</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to comparison function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + </record> + <constant name="SOURCE_CONTINUE" value="true" c:type="G_SOURCE_CONTINUE" version="2.32"> + <doc xml:space="preserve">Use this macro as the return value of a #GSourceFunc to leave +the #GSource in the main loop.</doc> + <type name="gboolean" c:type="gboolean"/> + </constant> + <function-macro name="SOURCE_FUNC" c:identifier="G_SOURCE_FUNC" version="2.58" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="f"> + <doc xml:space="preserve">a function pointer.</doc> + </parameter> + </parameters> + </function-macro> + <constant name="SOURCE_REMOVE" value="false" c:type="G_SOURCE_REMOVE" version="2.32"> + <doc xml:space="preserve">Use this macro as the return value of a #GSourceFunc to remove +the #GSource from the main loop.</doc> + <type name="gboolean" c:type="gboolean"/> + </constant> + <constant name="SQRT2" value="1.414214" c:type="G_SQRT2"> + <doc xml:space="preserve">The square root of two.</doc> + <type name="gdouble" c:type="gdouble"/> + </constant> + <function-macro name="STRINGIFY" c:identifier="G_STRINGIFY" introspectable="0"> + <doc xml:space="preserve">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!"; +]|</doc> + <parameters> + <parameter name="macro_or_string"> + <doc xml:space="preserve">a macro or a string</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="STRINGIFY_ARG" c:identifier="G_STRINGIFY_ARG" introspectable="0"> + <parameters> + <parameter name="contents"> + </parameter> + </parameters> + </function-macro> + <function-macro name="STRUCT_MEMBER" c:identifier="G_STRUCT_MEMBER" introspectable="0"> + <doc xml:space="preserve">Returns a member of a structure at a given offset, using the given type.</doc> + <parameters> + <parameter name="member_type"> + <doc xml:space="preserve">the type of the struct field</doc> + </parameter> + <parameter name="struct_p"> + <doc xml:space="preserve">a pointer to a struct</doc> + </parameter> + <parameter name="struct_offset"> + <doc xml:space="preserve">the offset of the field from the start of the struct, + in bytes</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="STRUCT_MEMBER_P" c:identifier="G_STRUCT_MEMBER_P" introspectable="0"> + <doc xml:space="preserve">Returns an untyped pointer to a given offset of a struct.</doc> + <parameters> + <parameter name="struct_p"> + <doc xml:space="preserve">a pointer to a struct</doc> + </parameter> + <parameter name="struct_offset"> + <doc xml:space="preserve">the offset from the start of the struct, in bytes</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="STRUCT_OFFSET" c:identifier="G_STRUCT_OFFSET" introspectable="0"> + <doc xml:space="preserve">Returns the offset, in bytes, of a member of a struct.</doc> + <parameters> + <parameter name="struct_type"> + <doc xml:space="preserve">a structure type, e.g. #GtkWidget</doc> + </parameter> + <parameter name="member"> + <doc xml:space="preserve">a field in the structure, e.g. @window</doc> + </parameter> + </parameters> + </function-macro> + <constant name="STR_DELIMITERS" value="_-|> <." c:type="G_STR_DELIMITERS"> + <doc xml:space="preserve">The standard delimiters, used in g_strdelimit().</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="SYSDEF_AF_INET" value="2" c:type="GLIB_SYSDEF_AF_INET"> + <type name="gint" c:type="gint"/> + </constant> + <constant name="SYSDEF_AF_INET6" value="10" c:type="GLIB_SYSDEF_AF_INET6"> + <type name="gint" c:type="gint"/> + </constant> + <constant name="SYSDEF_AF_UNIX" value="1" c:type="GLIB_SYSDEF_AF_UNIX"> + <type name="gint" c:type="gint"/> + </constant> + <constant name="SYSDEF_MSG_DONTROUTE" value="4" c:type="GLIB_SYSDEF_MSG_DONTROUTE"> + <type name="gint" c:type="gint"/> + </constant> + <constant name="SYSDEF_MSG_OOB" value="1" c:type="GLIB_SYSDEF_MSG_OOB"> + <type name="gint" c:type="gint"/> + </constant> + <constant name="SYSDEF_MSG_PEEK" value="2" c:type="GLIB_SYSDEF_MSG_PEEK"> + <type name="gint" c:type="gint"/> + </constant> + <record name="Scanner" c:type="GScanner"> + <doc xml:space="preserve">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.</doc> + <field name="user_data" writable="1"> + <doc xml:space="preserve">unused</doc> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="max_parse_errors" writable="1"> + <doc xml:space="preserve">unused</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="parse_errors" writable="1"> + <doc xml:space="preserve">g_scanner_error() increments this field</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="input_name" writable="1"> + <doc xml:space="preserve">name of input stream, featured by the default message handler</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="qdata" writable="1"> + <doc xml:space="preserve">quarked data</doc> + <type name="Data" c:type="GData*"/> + </field> + <field name="config" writable="1"> + <doc xml:space="preserve">link into the scanner configuration</doc> + <type name="ScannerConfig" c:type="GScannerConfig*"/> + </field> + <field name="token" writable="1"> + <doc xml:space="preserve">token parsed by the last g_scanner_get_next_token()</doc> + <type name="TokenType" c:type="GTokenType"/> + </field> + <field name="value" writable="1"> + <doc xml:space="preserve">value of the last token from g_scanner_get_next_token()</doc> + <type name="TokenValue" c:type="GTokenValue"/> + </field> + <field name="line" writable="1"> + <doc xml:space="preserve">line number of the last token from g_scanner_get_next_token()</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="position" writable="1"> + <doc xml:space="preserve">char number of the last token from g_scanner_get_next_token()</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="next_token" writable="1"> + <doc xml:space="preserve">token parsed by the last g_scanner_peek_next_token()</doc> + <type name="TokenType" c:type="GTokenType"/> + </field> + <field name="next_value" writable="1"> + <doc xml:space="preserve">value of the last token from g_scanner_peek_next_token()</doc> + <type name="TokenValue" c:type="GTokenValue"/> + </field> + <field name="next_line" writable="1"> + <doc xml:space="preserve">line number of the last token from g_scanner_peek_next_token()</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="next_position" writable="1"> + <doc xml:space="preserve">char number of the last token from g_scanner_peek_next_token()</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="symbol_table" readable="0" private="1"> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </field> + <field name="input_fd" readable="0" private="1"> + <type name="gint" c:type="gint"/> + </field> + <field name="text" readable="0" private="1"> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="text_end" readable="0" private="1"> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="buffer" readable="0" private="1"> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="scope_id" readable="0" private="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="msg_handler" writable="1"> + <doc xml:space="preserve">handler function for _warn and _error</doc> + <type name="ScannerMsgFunc" c:type="GScannerMsgFunc"/> + </field> + <method name="cur_line" c:identifier="g_scanner_cur_line"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the current line</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + </parameters> + </method> + <method name="cur_position" c:identifier="g_scanner_cur_position"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the current position on the line</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + </parameters> + </method> + <method name="cur_token" c:identifier="g_scanner_cur_token"> + <doc xml:space="preserve">Gets the current token type. This is simply the @token +field in the #GScanner structure.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the current token type</doc> + <type name="TokenType" c:type="GTokenType"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + </parameters> + </method> + <method name="cur_value" c:identifier="g_scanner_cur_value" introspectable="0"> + <doc xml:space="preserve">Gets the current token value. This is simply the @value +field in the #GScanner structure.</doc> + <return-value> + <doc xml:space="preserve">the current token value</doc> + <type name="TokenValue" c:type="GTokenValue"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + </parameters> + </method> + <method name="destroy" c:identifier="g_scanner_destroy"> + <doc xml:space="preserve">Frees all memory used by the #GScanner.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + </parameters> + </method> + <method name="eof" c:identifier="g_scanner_eof"> + <doc xml:space="preserve">Returns %TRUE if the scanner has reached the end of +the file or text buffer.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the scanner has reached the end of + the file or text buffer</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + </parameters> + </method> + <method name="error" c:identifier="g_scanner_error" introspectable="0"> + <doc xml:space="preserve">Outputs an error message, via the #GScanner message handler.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">the message format. See the printf() documentation</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the parameters to insert into the format string</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="get_next_token" c:identifier="g_scanner_get_next_token"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the type of the token</doc> + <type name="TokenType" c:type="GTokenType"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + </parameters> + </method> + <method name="input_file" c:identifier="g_scanner_input_file"> + <doc xml:space="preserve">Prepares to scan a file.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + <parameter name="input_fd" transfer-ownership="none"> + <doc xml:space="preserve">a file descriptor</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="input_text" c:identifier="g_scanner_input_text"> + <doc xml:space="preserve">Prepares to scan a text buffer.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + <parameter name="text" transfer-ownership="none"> + <doc xml:space="preserve">the text buffer to scan</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="text_len" transfer-ownership="none"> + <doc xml:space="preserve">the length of the text buffer</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="lookup_symbol" c:identifier="g_scanner_lookup_symbol"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the value of @symbol in the current scope, or %NULL + if @symbol is not bound in the current scope</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + <parameter name="symbol" transfer-ownership="none"> + <doc xml:space="preserve">the symbol to look up</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="peek_next_token" c:identifier="g_scanner_peek_next_token"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the type of the token</doc> + <type name="TokenType" c:type="GTokenType"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + </parameters> + </method> + <method name="scope_add_symbol" c:identifier="g_scanner_scope_add_symbol"> + <doc xml:space="preserve">Adds a symbol to the given scope.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + <parameter name="scope_id" transfer-ownership="none"> + <doc xml:space="preserve">the scope id</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="symbol" transfer-ownership="none"> + <doc xml:space="preserve">the symbol to add</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the value of the symbol</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="scope_foreach_symbol" c:identifier="g_scanner_scope_foreach_symbol" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + <parameter name="scope_id" transfer-ownership="none"> + <doc xml:space="preserve">the scope id</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function to call for each symbol/value pair</doc> + <type name="HFunc" c:type="GHFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to the function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="scope_lookup_symbol" c:identifier="g_scanner_scope_lookup_symbol"> + <doc xml:space="preserve">Looks up a symbol in a scope and return its value. If the +symbol is not bound in the scope, %NULL is returned.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the value of @symbol in the given scope, or %NULL + if @symbol is not bound in the given scope.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + <parameter name="scope_id" transfer-ownership="none"> + <doc xml:space="preserve">the scope id</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="symbol" transfer-ownership="none"> + <doc xml:space="preserve">the symbol to look up</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="scope_remove_symbol" c:identifier="g_scanner_scope_remove_symbol"> + <doc xml:space="preserve">Removes a symbol from a scope.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + <parameter name="scope_id" transfer-ownership="none"> + <doc xml:space="preserve">the scope id</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="symbol" transfer-ownership="none"> + <doc xml:space="preserve">the symbol to remove</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_scope" c:identifier="g_scanner_set_scope"> + <doc xml:space="preserve">Sets the current scope.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the old scope id</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + <parameter name="scope_id" transfer-ownership="none"> + <doc xml:space="preserve">the new scope id</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="sync_file_offset" c:identifier="g_scanner_sync_file_offset"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + </parameters> + </method> + <method name="unexp_token" c:identifier="g_scanner_unexp_token"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + <parameter name="expected_token" transfer-ownership="none"> + <doc xml:space="preserve">the expected token</doc> + <type name="TokenType" c:type="GTokenType"/> + </parameter> + <parameter name="identifier_spec" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="symbol_spec" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="symbol_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the symbol, if the scanner's current + token is a symbol.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a message string to output at the end of the + warning/error, or %NULL.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="is_error" transfer-ownership="none"> + <doc xml:space="preserve">if %TRUE it is output as an error. If %FALSE it is + output as a warning.</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="warn" c:identifier="g_scanner_warn" introspectable="0"> + <doc xml:space="preserve">Outputs a warning message, via the #GScanner message handler.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </instance-parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">the message format. See the printf() documentation</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the parameters to insert into the format string</doc> + <varargs/> + </parameter> + </parameters> + </method> + <function name="new" c:identifier="g_scanner_new" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the new #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </return-value> + <parameters> + <parameter name="config_templ" transfer-ownership="none"> + <doc xml:space="preserve">the initial scanner settings</doc> + <type name="ScannerConfig" c:type="const GScannerConfig*"/> + </parameter> + </parameters> + </function> + </record> + <record name="ScannerConfig" c:type="GScannerConfig"> + <doc xml:space="preserve">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.</doc> + <field name="cset_skip_characters" writable="1"> + <doc xml:space="preserve">specifies which characters should be skipped + by the scanner (the default is the whitespace characters: space, + tab, carriage-return and line-feed).</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="cset_identifier_first" writable="1"> + <doc xml:space="preserve">specifies the characters which can start + identifiers (the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z).</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="cset_identifier_nth" writable="1"> + <doc xml:space="preserve">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).</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="cpair_comment_single" writable="1"> + <doc xml:space="preserve">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).</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="case_sensitive" writable="1" bits="1"> + <doc xml:space="preserve">specifies if symbols are case sensitive (the + default is %FALSE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="skip_comment_multi" writable="1" bits="1"> + <doc xml:space="preserve">specifies if multi-line comments are skipped + and not returned as tokens (the default is %TRUE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="skip_comment_single" writable="1" bits="1"> + <doc xml:space="preserve">specifies if single-line comments are skipped + and not returned as tokens (the default is %TRUE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="scan_comment_multi" writable="1" bits="1"> + <doc xml:space="preserve">specifies if multi-line comments are recognized + (the default is %TRUE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="scan_identifier" writable="1" bits="1"> + <doc xml:space="preserve">specifies if identifiers are recognized (the + default is %TRUE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="scan_identifier_1char" writable="1" bits="1"> + <doc xml:space="preserve">specifies if single-character + identifiers are recognized (the default is %FALSE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="scan_identifier_NULL" writable="1" bits="1"> + <doc xml:space="preserve">specifies if %NULL is reported as + %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="scan_symbols" writable="1" bits="1"> + <doc xml:space="preserve">specifies if symbols are recognized (the default + is %TRUE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="scan_binary" writable="1" bits="1"> + <doc xml:space="preserve">specifies if binary numbers are recognized (the + default is %FALSE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="scan_octal" writable="1" bits="1"> + <doc xml:space="preserve">specifies if octal numbers are recognized (the + default is %TRUE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="scan_float" writable="1" bits="1"> + <doc xml:space="preserve">specifies if floating point numbers are recognized + (the default is %TRUE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="scan_hex" writable="1" bits="1"> + <doc xml:space="preserve">specifies if hexadecimal numbers are recognized (the + default is %TRUE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="scan_hex_dollar" writable="1" bits="1"> + <doc xml:space="preserve">specifies if '$' is recognized as a prefix for + hexadecimal numbers (the default is %FALSE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="scan_string_sq" writable="1" bits="1"> + <doc xml:space="preserve">specifies if strings can be enclosed in single + quotes (the default is %TRUE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="scan_string_dq" writable="1" bits="1"> + <doc xml:space="preserve">specifies if strings can be enclosed in double + quotes (the default is %TRUE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="numbers_2_int" writable="1" bits="1"> + <doc xml:space="preserve">specifies if binary, octal and hexadecimal numbers + are reported as #G_TOKEN_INT (the default is %TRUE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="int_2_float" writable="1" bits="1"> + <doc xml:space="preserve">specifies if all numbers are reported as %G_TOKEN_FLOAT + (the default is %FALSE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="identifier_2_string" writable="1" bits="1"> + <doc xml:space="preserve">specifies if identifiers are reported as strings + (the default is %FALSE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="char_2_token" writable="1" bits="1"> + <doc xml:space="preserve">specifies if characters are reported by setting + `token = ch` or as %G_TOKEN_CHAR (the default is %TRUE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="symbol_2_token" writable="1" bits="1"> + <doc xml:space="preserve">specifies if symbols are reported by setting + `token = v_symbol` or as %G_TOKEN_SYMBOL (the default is %FALSE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="scope_0_fallback" writable="1" bits="1"> + <doc xml:space="preserve">specifies if a symbol is searched for in the + default scope in addition to the current scope (the default is %FALSE).</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="store_int64" writable="1" bits="1"> + <doc xml:space="preserve">use value.v_int64 rather than v_int</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="padding_dummy" readable="0" private="1"> + <type name="guint" c:type="guint"/> + </field> + </record> + <callback name="ScannerMsgFunc" c:type="GScannerMsgFunc"> + <doc xml:space="preserve">Specifies the type of the message handler function.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="scanner" transfer-ownership="none"> + <doc xml:space="preserve">a #GScanner</doc> + <type name="Scanner" c:type="GScanner*"/> + </parameter> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">the message</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the message signals an error, + %FALSE if it signals a warning.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </callback> + <enumeration name="SeekType" c:type="GSeekType"> + <doc xml:space="preserve">An enumeration specifying the base position for a +g_io_channel_seek_position() operation.</doc> + <member name="cur" value="0" c:identifier="G_SEEK_CUR"> + <doc xml:space="preserve">the current position in the file.</doc> + </member> + <member name="set" value="1" c:identifier="G_SEEK_SET"> + <doc xml:space="preserve">the start of the file.</doc> + </member> + <member name="end" value="2" c:identifier="G_SEEK_END"> + <doc xml:space="preserve">the end of the file.</doc> + </member> + </enumeration> + <record name="Sequence" c:type="GSequence" disguised="1"> + <doc xml:space="preserve">The #GSequence struct is an opaque data type representing a +[sequence][glib-Sequences] data type.</doc> + <method name="append" c:identifier="g_sequence_append" version="2.14"> + <doc xml:space="preserve">Adds a new item to the end of @seq.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an iterator pointing to the new item</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new item</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="foreach" c:identifier="g_sequence_foreach" version="2.14" introspectable="0"> + <doc xml:space="preserve">Calls @func for each item in the sequence passing @user_data +to the function. @func must not modify the sequence itself.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + <parameter name="func" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">the function to call for each item in @seq</doc> + <type name="Func" c:type="GFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="free" c:identifier="g_sequence_free" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_begin_iter" c:identifier="g_sequence_get_begin_iter" version="2.14"> + <doc xml:space="preserve">Returns the begin iterator for @seq.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the begin iterator for @seq.</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_end_iter" c:identifier="g_sequence_get_end_iter" version="2.14"> + <doc xml:space="preserve">Returns the end iterator for @seg</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the end iterator for @seq</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_iter_at_pos" c:identifier="g_sequence_get_iter_at_pos" version="2.14"> + <doc xml:space="preserve">Returns the iterator at position @pos. If @pos is negative or larger +than the number of items in @seq, the end iterator is returned.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The #GSequenceIter at position @pos</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + <parameter name="pos" transfer-ownership="none"> + <doc xml:space="preserve">a position in @seq, or -1 for the end</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="get_length" c:identifier="g_sequence_get_length" version="2.14"> + <doc xml:space="preserve">Returns the positive length (>= 0) 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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the length of @seq</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + </parameters> + </method> + <method name="insert_sorted" c:identifier="g_sequence_insert_sorted" version="2.14" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter pointing to the new item.</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to insert</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="cmp_func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function used to compare items in the sequence</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @cmp_func.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="insert_sorted_iter" c:identifier="g_sequence_insert_sorted_iter" version="2.14" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter pointing to the new item</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data for the new item</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="iter_cmp" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function used to compare iterators in the sequence</doc> + <type name="SequenceIterCompareFunc" c:type="GSequenceIterCompareFunc"/> + </parameter> + <parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @iter_cmp</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="is_empty" c:identifier="g_sequence_is_empty" version="2.48"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the sequence is empty, otherwise %FALSE.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + </parameters> + </method> + <method name="lookup" c:identifier="g_sequence_lookup" version="2.28" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">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</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to look up</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="cmp_func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function used to compare items in the sequence</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @cmp_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="lookup_iter" c:identifier="g_sequence_lookup_iter" version="2.28" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">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</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to look up</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="iter_cmp" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function used to compare iterators in the sequence</doc> + <type name="SequenceIterCompareFunc" c:type="GSequenceIterCompareFunc"/> + </parameter> + <parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @iter_cmp</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="prepend" c:identifier="g_sequence_prepend" version="2.14"> + <doc xml:space="preserve">Adds a new item to the front of @seq</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an iterator pointing to the new item</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new item</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="search" c:identifier="g_sequence_search" version="2.14" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an #GSequenceIter pointing to the position where @data + would have been inserted according to @cmp_func and @cmp_data</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data for the new item</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="cmp_func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function used to compare items in the sequence</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @cmp_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="search_iter" c:identifier="g_sequence_search_iter" version="2.14" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter pointing to the position in @seq + where @data would have been inserted according to @iter_cmp + and @cmp_data</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data for the new item</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="iter_cmp" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function used to compare iterators in the sequence</doc> + <type name="SequenceIterCompareFunc" c:type="GSequenceIterCompareFunc"/> + </parameter> + <parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @iter_cmp</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="sort" c:identifier="g_sequence_sort" version="2.14" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + <parameter name="cmp_func" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">the function used to sort the sequence</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @cmp_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="sort_iter" c:identifier="g_sequence_sort_iter" version="2.14" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="seq" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </instance-parameter> + <parameter name="cmp_func" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">the function used to compare iterators in the sequence</doc> + <type name="SequenceIterCompareFunc" c:type="GSequenceIterCompareFunc"/> + </parameter> + <parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @cmp_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <function name="foreach_range" c:identifier="g_sequence_foreach_range" version="2.14" introspectable="0"> + <doc xml:space="preserve">Calls @func for each item in the range (@begin, @end) passing +@user_data to the function. @func must not modify the sequence +itself.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="begin" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="end" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="func" transfer-ownership="none" closure="3"> + <doc xml:space="preserve">a #GFunc</doc> + <type name="Func" c:type="GFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="get" c:identifier="g_sequence_get" version="2.14"> + <doc xml:space="preserve">Returns the data that @iter points to.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the data that @iter points to</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + </parameters> + </function> + <function name="insert_before" c:identifier="g_sequence_insert_before" version="2.14"> + <doc xml:space="preserve">Inserts a new item just before the item pointed to by @iter.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an iterator pointing to the new item</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new item</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="move" c:identifier="g_sequence_move" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="src" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter pointing to the item to move</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="dest" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter pointing to the position to which + the item is moved</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + </parameters> + </function> + <function name="move_range" c:identifier="g_sequence_move_range" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="dest" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="begin" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="end" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + </parameters> + </function> + <function name="new" c:identifier="g_sequence_new" version="2.14" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSequence</doc> + <type name="Sequence" c:type="GSequence*"/> + </return-value> + <parameters> + <parameter name="data_destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a #GDestroyNotify function, or %NULL</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="range_get_midpoint" c:identifier="g_sequence_range_get_midpoint" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter pointing somewhere in the + (@begin, @end) range</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <parameter name="begin" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="end" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + </parameters> + </function> + <function name="remove" c:identifier="g_sequence_remove" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + </parameters> + </function> + <function name="remove_range" c:identifier="g_sequence_remove_range" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="begin" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="end" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + </parameters> + </function> + <function name="set" c:identifier="g_sequence_set" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">new data for the item</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="sort_changed" c:identifier="g_sequence_sort_changed" version="2.14" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">A #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="cmp_func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function used to compare items in the sequence</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @cmp_func.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="sort_changed_iter" c:identifier="g_sequence_sort_changed_iter" version="2.14" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="iter_cmp" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function used to compare iterators in the sequence</doc> + <type name="SequenceIterCompareFunc" c:type="GSequenceIterCompareFunc"/> + </parameter> + <parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @cmp_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="swap" c:identifier="g_sequence_swap" version="2.14"> + <doc xml:space="preserve">Swaps the items pointed to by @a and @b. It is allowed for @a and @b +to point into difference sequences.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="a" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="b" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + </parameters> + </function> + </record> + <record name="SequenceIter" c:type="GSequenceIter" disguised="1"> + <doc xml:space="preserve">The #GSequenceIter struct is an opaque data type representing an +iterator pointing into a #GSequence.</doc> + <method name="compare" c:identifier="g_sequence_iter_compare" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a negative number if @a comes before @b, 0 if they are + equal, and a positive number if @a comes after @b</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="a" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </instance-parameter> + <parameter name="b" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + </parameters> + </method> + <method name="get_position" c:identifier="g_sequence_iter_get_position" version="2.14"> + <doc xml:space="preserve">Returns the position of @iter</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the position of @iter</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_sequence" c:identifier="g_sequence_iter_get_sequence" version="2.14"> + <doc xml:space="preserve">Returns the #GSequence that @iter points into.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GSequence that @iter points into</doc> + <type name="Sequence" c:type="GSequence*"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_begin" c:identifier="g_sequence_iter_is_begin" version="2.14"> + <doc xml:space="preserve">Returns whether @iter is the begin iterator</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether @iter is the begin iterator</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_end" c:identifier="g_sequence_iter_is_end" version="2.14"> + <doc xml:space="preserve">Returns whether @iter is the end iterator</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Whether @iter is the end iterator</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </instance-parameter> + </parameters> + </method> + <method name="move" c:identifier="g_sequence_iter_move" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter which is @delta positions away from @iter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </instance-parameter> + <parameter name="delta" transfer-ownership="none"> + <doc xml:space="preserve">A positive or negative number indicating how many positions away + from @iter the returned #GSequenceIter will be</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="next" c:identifier="g_sequence_iter_next" version="2.14"> + <doc xml:space="preserve">Returns an iterator pointing to the next position after @iter. +If @iter is the end iterator, the end iterator is returned.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter pointing to the next position after @iter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </instance-parameter> + </parameters> + </method> + <method name="prev" c:identifier="g_sequence_iter_prev" version="2.14"> + <doc xml:space="preserve">Returns an iterator pointing to the previous position before @iter. +If @iter is the begin iterator, the begin iterator is returned.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter pointing to the previous position + before @iter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </instance-parameter> + </parameters> + </method> + </record> + <callback name="SequenceIterCompareFunc" c:type="GSequenceIterCompareFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">zero if the iterators are equal, a negative value if @a + comes before @b, and a positive value if @b comes before @a.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="a" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="b" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <enumeration name="ShellError" c:type="GShellError" glib:error-domain="g-shell-error-quark"> + <doc xml:space="preserve">Error codes returned by shell functions.</doc> + <member name="bad_quoting" value="0" c:identifier="G_SHELL_ERROR_BAD_QUOTING"> + <doc xml:space="preserve">Mismatched or otherwise mangled quoting.</doc> + </member> + <member name="empty_string" value="1" c:identifier="G_SHELL_ERROR_EMPTY_STRING"> + <doc xml:space="preserve">String to be parsed was empty.</doc> + </member> + <member name="failed" value="2" c:identifier="G_SHELL_ERROR_FAILED"> + <doc xml:space="preserve">Some other error.</doc> + </member> + </enumeration> + <enumeration name="SliceConfig" c:type="GSliceConfig"> + <member name="always_malloc" value="1" c:identifier="G_SLICE_CONFIG_ALWAYS_MALLOC"> + </member> + <member name="bypass_magazines" value="2" c:identifier="G_SLICE_CONFIG_BYPASS_MAGAZINES"> + </member> + <member name="working_set_msecs" value="3" c:identifier="G_SLICE_CONFIG_WORKING_SET_MSECS"> + </member> + <member name="color_increment" value="4" c:identifier="G_SLICE_CONFIG_COLOR_INCREMENT"> + </member> + <member name="chunk_sizes" value="5" c:identifier="G_SLICE_CONFIG_CHUNK_SIZES"> + </member> + <member name="contention_counter" value="6" c:identifier="G_SLICE_CONFIG_CONTENTION_COUNTER"> + </member> + </enumeration> + <record name="Source" c:type="GSource" glib:type-name="GSource" glib:get-type="g_source_get_type" c:symbol-prefix="source"> + <doc xml:space="preserve">The `GSource` struct is an opaque data type +representing an event source.</doc> + <field name="callback_data" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="callback_funcs" readable="0" private="1"> + <type name="SourceCallbackFuncs" c:type="GSourceCallbackFuncs*"/> + </field> + <field name="source_funcs" readable="0" private="1"> + <type name="SourceFuncs" c:type="const GSourceFuncs*"/> + </field> + <field name="ref_count" readable="0" private="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="context" readable="0" private="1"> + <type name="MainContext" c:type="GMainContext*"/> + </field> + <field name="priority" readable="0" private="1"> + <type name="gint" c:type="gint"/> + </field> + <field name="flags" readable="0" private="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="source_id" readable="0" private="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="poll_fds" readable="0" private="1"> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </field> + <field name="prev" readable="0" private="1"> + <type name="Source" c:type="GSource*"/> + </field> + <field name="next" readable="0" private="1"> + <type name="Source" c:type="GSource*"/> + </field> + <field name="name" readable="0" private="1"> + <type name="utf8" c:type="char*"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="SourcePrivate" c:type="GSourcePrivate*"/> + </field> + <constructor name="new" c:identifier="g_source_new"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the newly-created #GSource.</doc> + <type name="Source" c:type="GSource*"/> + </return-value> + <parameters> + <parameter name="source_funcs" transfer-ownership="none"> + <doc xml:space="preserve">structure containing functions that implement + the sources behavior.</doc> + <type name="SourceFuncs" c:type="GSourceFuncs*"/> + </parameter> + <parameter name="struct_size" transfer-ownership="none"> + <doc xml:space="preserve">size of the #GSource structure to create.</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </constructor> + <method name="add_child_source" c:identifier="g_source_add_child_source" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="child_source" transfer-ownership="none"> + <doc xml:space="preserve">a second #GSource that @source should "poll"</doc> + <type name="Source" c:type="GSource*"/> + </parameter> + </parameters> + </method> + <method name="add_poll" c:identifier="g_source_add_poll"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollFD structure holding information about a file + descriptor to watch.</doc> + <type name="PollFD" c:type="GPollFD*"/> + </parameter> + </parameters> + </method> + <method name="add_unix_fd" c:identifier="g_source_add_unix_fd" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an opaque tag</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">the fd to monitor</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="events" transfer-ownership="none"> + <doc xml:space="preserve">an event mask</doc> + <type name="IOCondition" c:type="GIOCondition"/> + </parameter> + </parameters> + </method> + <method name="attach" c:identifier="g_source_attach"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ID (greater than 0) for the source within the + #GMainContext.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMainContext (if %NULL, the default context will be used)</doc> + <type name="MainContext" c:type="GMainContext*"/> + </parameter> + </parameters> + </method> + <method name="destroy" c:identifier="g_source_destroy"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_can_recurse" c:identifier="g_source_get_can_recurse"> + <doc xml:space="preserve">Checks whether a source is allowed to be called recursively. +see g_source_set_can_recurse().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether recursion is allowed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_context" c:identifier="g_source_get_context"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the #GMainContext with which the + source is associated, or %NULL if the context has not + yet been added to a source.</doc> + <type name="MainContext" c:type="GMainContext*"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_current_time" c:identifier="g_source_get_current_time" deprecated="1" deprecated-version="2.28"> + <doc xml:space="preserve">This function ignores @source and is otherwise the same as +g_get_current_time().</doc> + <doc-deprecated xml:space="preserve">use g_source_get_time() instead</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="timeval" transfer-ownership="none"> + <doc xml:space="preserve">#GTimeVal structure in which to store current time.</doc> + <type name="TimeVal" c:type="GTimeVal*"/> + </parameter> + </parameters> + </method> + <method name="get_id" c:identifier="g_source_get_id"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ID (greater than 0) for the source</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_name" c:identifier="g_source_get_name" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the name of the source</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_priority" c:identifier="g_source_get_priority"> + <doc xml:space="preserve">Gets the priority of a source.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the priority of the source</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_ready_time" c:identifier="g_source_get_ready_time"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the monotonic ready time, -1 for "never"</doc> + <type name="gint64" c:type="gint64"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_time" c:identifier="g_source_get_time" version="2.28"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the monotonic time in microseconds</doc> + <type name="gint64" c:type="gint64"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_destroyed" c:identifier="g_source_is_destroyed" version="2.12"> + <doc xml:space="preserve">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; + + g_mutex_lock (&self->idle_id_mutex); + // do stuff with self + self->idle_id = 0; + g_mutex_unlock (&self->idle_id_mutex); + + return G_SOURCE_REMOVE; +} + +static void +some_widget_do_stuff_later (SomeWidget *self) +{ + g_mutex_lock (&self->idle_id_mutex); + self->idle_id = g_idle_add (idle_callback, self); + g_mutex_unlock (&self->idle_id_mutex); +} + +static void +some_widget_init (SomeWidget *self) +{ + g_mutex_init (&self->idle_id_mutex); + + // ... +} + +static void +some_widget_finalize (GObject *object) +{ + SomeWidget *self = SOME_WIDGET (object); + + if (self->idle_id) + g_source_remove (self->idle_id); + + g_mutex_clear (&self->idle_id_mutex); + + 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; + + g_mutex_lock (&self->idle_id_mutex); + if (!g_source_is_destroyed (g_main_current_source ())) + { + // do stuff with self + } + g_mutex_unlock (&self->idle_id_mutex); + + 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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the source has been destroyed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + </parameters> + </method> + <method name="modify_unix_fd" c:identifier="g_source_modify_unix_fd" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="tag" transfer-ownership="none"> + <doc xml:space="preserve">the tag from g_source_add_unix_fd()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="new_events" transfer-ownership="none"> + <doc xml:space="preserve">the new event mask to watch</doc> + <type name="IOCondition" c:type="GIOCondition"/> + </parameter> + </parameters> + </method> + <method name="query_unix_fd" c:identifier="g_source_query_unix_fd" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the conditions reported on the fd</doc> + <type name="IOCondition" c:type="GIOCondition"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="tag" transfer-ownership="none"> + <doc xml:space="preserve">the tag from g_source_add_unix_fd()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_source_ref"> + <doc xml:space="preserve">Increases the reference count on a source by one.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">@source</doc> + <type name="Source" c:type="GSource*"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + </parameters> + </method> + <method name="remove_child_source" c:identifier="g_source_remove_child_source" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="child_source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource previously passed to + g_source_add_child_source().</doc> + <type name="Source" c:type="GSource*"/> + </parameter> + </parameters> + </method> + <method name="remove_poll" c:identifier="g_source_remove_poll"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollFD structure previously passed to g_source_add_poll().</doc> + <type name="PollFD" c:type="GPollFD*"/> + </parameter> + </parameters> + </method> + <method name="remove_unix_fd" c:identifier="g_source_remove_unix_fd" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="tag" transfer-ownership="none"> + <doc xml:space="preserve">the tag from g_source_add_unix_fd()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="set_callback" c:identifier="g_source_set_callback"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">the source</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="func" transfer-ownership="none" scope="notified" closure="1" destroy="2"> + <doc xml:space="preserve">a callback function</doc> + <type name="SourceFunc" c:type="GSourceFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a function to call when @data is no longer in use, or %NULL.</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="set_callback_indirect" c:identifier="g_source_set_callback_indirect"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">the source</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="callback_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">pointer to callback data "object"</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="callback_funcs" transfer-ownership="none"> + <doc xml:space="preserve">functions for reference counting @callback_data + and getting the callback and data</doc> + <type name="SourceCallbackFuncs" c:type="GSourceCallbackFuncs*"/> + </parameter> + </parameters> + </method> + <method name="set_can_recurse" c:identifier="g_source_set_can_recurse"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="can_recurse" transfer-ownership="none"> + <doc xml:space="preserve">whether recursion is allowed for this source</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_dispose_function" c:identifier="g_source_set_dispose_function" version="2.64" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">A #GSource to set the dispose function on</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="dispose" transfer-ownership="none"> + <doc xml:space="preserve">#GSourceDisposeFunc to set on the source</doc> + <type name="SourceDisposeFunc" c:type="GSourceDisposeFunc"/> + </parameter> + </parameters> + </method> + <method name="set_funcs" c:identifier="g_source_set_funcs" version="2.12"> + <doc xml:space="preserve">Sets the source functions (can be used to override +default implementations) of an unattached source.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="funcs" transfer-ownership="none"> + <doc xml:space="preserve">the new #GSourceFuncs</doc> + <type name="SourceFuncs" c:type="GSourceFuncs*"/> + </parameter> + </parameters> + </method> + <method name="set_name" c:identifier="g_source_set_name" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">debug name for the source</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_priority" c:identifier="g_source_set_priority"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="priority" transfer-ownership="none"> + <doc xml:space="preserve">the new priority.</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="set_ready_time" c:identifier="g_source_set_ready_time" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + <parameter name="ready_time" transfer-ownership="none"> + <doc xml:space="preserve">the monotonic time at which the source will be ready, + 0 for "immediately", -1 for "never"</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_source_unref"> + <doc xml:space="preserve">Decreases the reference count of a source by one. If the +resulting reference count is zero the source and associated +memory will be destroyed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource</doc> + <type name="Source" c:type="GSource*"/> + </instance-parameter> + </parameters> + </method> + <function name="remove" c:identifier="g_source_remove"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">For historical reasons, this function always returns %TRUE</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="tag" transfer-ownership="none"> + <doc xml:space="preserve">the ID of the source to remove.</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="remove_by_funcs_user_data" c:identifier="g_source_remove_by_funcs_user_data"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a source was found and removed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="funcs" transfer-ownership="none"> + <doc xml:space="preserve">The @source_funcs passed to g_source_new()</doc> + <type name="SourceFuncs" c:type="GSourceFuncs*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the user data for the callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="remove_by_user_data" c:identifier="g_source_remove_by_user_data"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a source was found and removed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the user_data for the callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="set_name_by_id" c:identifier="g_source_set_name_by_id" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="tag" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource ID</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">debug name for the source</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + </record> + <record name="SourceCallbackFuncs" c:type="GSourceCallbackFuncs"> + <doc xml:space="preserve">The `GSourceCallbackFuncs` struct contains +functions for managing callback objects.</doc> + <field name="ref"> + <callback name="ref"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="cb_data" transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="unref"> + <callback name="unref"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="cb_data" transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get" introspectable="0"> + <callback name="get" introspectable="0"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="cb_data" transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="source" transfer-ownership="none"> + <type name="Source" c:type="GSource*"/> + </parameter> + <parameter name="func" transfer-ownership="none" closure="3"> + <type name="SourceFunc" c:type="GSourceFunc*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <callback name="SourceDisposeFunc" c:type="GSourceDisposeFunc" version="2.64"> + <doc xml:space="preserve">Dispose function for @source. See g_source_set_dispose_function() for +details.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">#GSource that is currently being disposed</doc> + <type name="Source" c:type="GSource*"/> + </parameter> + </parameters> + </callback> + <callback name="SourceDummyMarshal" c:type="GSourceDummyMarshal"> + <doc xml:space="preserve">This is just a placeholder for #GClosureMarshal, +which cannot be used here for dependency reasons.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + <callback name="SourceFunc" c:type="GSourceFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%FALSE if the source should be removed. #G_SOURCE_CONTINUE and +#G_SOURCE_REMOVE are more memorable names for the return value.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="0"> + <doc xml:space="preserve">data passed to the function, set when the source was + created with one of the above functions</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="SourceFuncs" c:type="GSourceFuncs"> + <doc xml:space="preserve">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.</doc> + <field name="prepare"> + <callback name="prepare"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="source" transfer-ownership="none"> + <type name="Source" c:type="GSource*"/> + </parameter> + <parameter name="timeout_" transfer-ownership="none"> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="check"> + <callback name="check"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="source" transfer-ownership="none"> + <type name="Source" c:type="GSource*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="dispatch" introspectable="0"> + <callback name="dispatch" introspectable="0"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="source" transfer-ownership="none"> + <type name="Source" c:type="GSource*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" closure="2"> + <type name="SourceFunc" c:type="GSourceFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="finalize"> + <callback name="finalize"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="source" transfer-ownership="none"> + <type name="Source" c:type="GSource*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="closure_callback" readable="0" private="1"> + <type name="SourceFunc" c:type="GSourceFunc"/> + </field> + <field name="closure_marshal" readable="0" private="1"> + <type name="SourceDummyMarshal" c:type="GSourceDummyMarshal"/> + </field> + </record> + <record name="SourcePrivate" c:type="GSourcePrivate" disguised="1"/> + <callback name="SpawnChildSetupFunc" c:type="GSpawnChildSetupFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="0"> + <doc xml:space="preserve">user data to pass to the function.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <enumeration name="SpawnError" c:type="GSpawnError" glib:error-domain="g-exec-error-quark"> + <doc xml:space="preserve">Error codes returned by spawning processes.</doc> + <member name="fork" value="0" c:identifier="G_SPAWN_ERROR_FORK"> + <doc xml:space="preserve">Fork failed due to lack of memory.</doc> + </member> + <member name="read" value="1" c:identifier="G_SPAWN_ERROR_READ"> + <doc xml:space="preserve">Read or select on pipes failed.</doc> + </member> + <member name="chdir" value="2" c:identifier="G_SPAWN_ERROR_CHDIR"> + <doc xml:space="preserve">Changing to working directory failed.</doc> + </member> + <member name="acces" value="3" c:identifier="G_SPAWN_ERROR_ACCES"> + <doc xml:space="preserve">execv() returned `EACCES`</doc> + </member> + <member name="perm" value="4" c:identifier="G_SPAWN_ERROR_PERM"> + <doc xml:space="preserve">execv() returned `EPERM`</doc> + </member> + <member name="too_big" value="5" c:identifier="G_SPAWN_ERROR_TOO_BIG"> + <doc xml:space="preserve">execv() returned `E2BIG`</doc> + </member> + <member name="2big" value="5" c:identifier="G_SPAWN_ERROR_2BIG"> + <doc xml:space="preserve">deprecated alias for %G_SPAWN_ERROR_TOO_BIG (deprecated since GLib 2.32)</doc> + </member> + <member name="noexec" value="6" c:identifier="G_SPAWN_ERROR_NOEXEC"> + <doc xml:space="preserve">execv() returned `ENOEXEC`</doc> + </member> + <member name="nametoolong" value="7" c:identifier="G_SPAWN_ERROR_NAMETOOLONG"> + <doc xml:space="preserve">execv() returned `ENAMETOOLONG`</doc> + </member> + <member name="noent" value="8" c:identifier="G_SPAWN_ERROR_NOENT"> + <doc xml:space="preserve">execv() returned `ENOENT`</doc> + </member> + <member name="nomem" value="9" c:identifier="G_SPAWN_ERROR_NOMEM"> + <doc xml:space="preserve">execv() returned `ENOMEM`</doc> + </member> + <member name="notdir" value="10" c:identifier="G_SPAWN_ERROR_NOTDIR"> + <doc xml:space="preserve">execv() returned `ENOTDIR`</doc> + </member> + <member name="loop" value="11" c:identifier="G_SPAWN_ERROR_LOOP"> + <doc xml:space="preserve">execv() returned `ELOOP`</doc> + </member> + <member name="txtbusy" value="12" c:identifier="G_SPAWN_ERROR_TXTBUSY"> + <doc xml:space="preserve">execv() returned `ETXTBUSY`</doc> + </member> + <member name="io" value="13" c:identifier="G_SPAWN_ERROR_IO"> + <doc xml:space="preserve">execv() returned `EIO`</doc> + </member> + <member name="nfile" value="14" c:identifier="G_SPAWN_ERROR_NFILE"> + <doc xml:space="preserve">execv() returned `ENFILE`</doc> + </member> + <member name="mfile" value="15" c:identifier="G_SPAWN_ERROR_MFILE"> + <doc xml:space="preserve">execv() returned `EMFILE`</doc> + </member> + <member name="inval" value="16" c:identifier="G_SPAWN_ERROR_INVAL"> + <doc xml:space="preserve">execv() returned `EINVAL`</doc> + </member> + <member name="isdir" value="17" c:identifier="G_SPAWN_ERROR_ISDIR"> + <doc xml:space="preserve">execv() returned `EISDIR`</doc> + </member> + <member name="libbad" value="18" c:identifier="G_SPAWN_ERROR_LIBBAD"> + <doc xml:space="preserve">execv() returned `ELIBBAD`</doc> + </member> + <member name="failed" value="19" c:identifier="G_SPAWN_ERROR_FAILED"> + <doc xml:space="preserve">Some other fatal failure, + `error->message` should explain.</doc> + </member> + </enumeration> + <bitfield name="SpawnFlags" c:type="GSpawnFlags"> + <doc xml:space="preserve">Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes().</doc> + <member name="default" value="0" c:identifier="G_SPAWN_DEFAULT"> + <doc xml:space="preserve">no flags, default behaviour</doc> + </member> + <member name="leave_descriptors_open" value="1" c:identifier="G_SPAWN_LEAVE_DESCRIPTORS_OPEN"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="do_not_reap_child" value="2" c:identifier="G_SPAWN_DO_NOT_REAP_CHILD"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="search_path" value="4" c:identifier="G_SPAWN_SEARCH_PATH"> + <doc xml:space="preserve">`argv[0]` need not be an absolute path, it will be + looked for in the user's `PATH`.</doc> + </member> + <member name="stdout_to_dev_null" value="8" c:identifier="G_SPAWN_STDOUT_TO_DEV_NULL"> + <doc xml:space="preserve">the child's standard output will be discarded, + instead of going to the same location as the parent's standard output.</doc> + </member> + <member name="stderr_to_dev_null" value="16" c:identifier="G_SPAWN_STDERR_TO_DEV_NULL"> + <doc xml:space="preserve">the child's standard error will be discarded.</doc> + </member> + <member name="child_inherits_stdin" value="32" c:identifier="G_SPAWN_CHILD_INHERITS_STDIN"> + <doc xml:space="preserve">the child will inherit the parent's standard + input (by default, the child's standard input is attached to `/dev/null`).</doc> + </member> + <member name="file_and_argv_zero" value="64" c:identifier="G_SPAWN_FILE_AND_ARGV_ZERO"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="search_path_from_envp" value="128" c:identifier="G_SPAWN_SEARCH_PATH_FROM_ENVP"> + <doc xml:space="preserve">if `argv[0]` is not an absolute path, + it will be looked for in the `PATH` from the passed child environment. + Since: 2.34</doc> + </member> + <member name="cloexec_pipes" value="256" c:identifier="G_SPAWN_CLOEXEC_PIPES"> + <doc xml:space="preserve">create all pipes with the `O_CLOEXEC` flag set. + Since: 2.40</doc> + </member> + </bitfield> + <record name="StatBuf" c:type="GStatBuf" disguised="1"> + <doc xml:space="preserve">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.</doc> + </record> + <record name="String" c:type="GString" glib:type-name="GString" glib:get-type="g_gstring_get_type" c:symbol-prefix="gstring"> + <doc xml:space="preserve">The GString struct contains the public fields of a GString.</doc> + <field name="str" writable="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="len" writable="1"> + <doc xml:space="preserve">contains the length of the string, not including the + terminating nul byte.</doc> + <type name="gsize" c:type="gsize"/> + </field> + <field name="allocated_len" writable="1"> + <doc xml:space="preserve">the number of bytes that can be stored in the + string before it needs to be reallocated. May be larger than @len.</doc> + <type name="gsize" c:type="gsize"/> + </field> + <method name="append" c:identifier="g_string_append"> + <doc xml:space="preserve">Adds a string onto the end of a #GString, expanding +it if necessary.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">the string to append onto the end of @string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="append_c" c:identifier="g_string_append_c"> + <doc xml:space="preserve">Adds a byte onto the end of a #GString, expanding +it if necessary.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">the byte to append onto the end of @string</doc> + <type name="gchar" c:type="gchar"/> + </parameter> + </parameters> + </method> + <method name="append_len" c:identifier="g_string_append_len"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">bytes to append</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">number of bytes of @val to use, or -1 for all of @val</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </method> + <method name="append_printf" c:identifier="g_string_append_printf" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">the string format. See the printf() documentation</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the parameters to insert into the format string</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="append_unichar" c:identifier="g_string_append_unichar"> + <doc xml:space="preserve">Converts a Unicode character into UTF-8, and appends it +to the string.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="wc" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </method> + <method name="append_uri_escaped" c:identifier="g_string_append_uri_escaped" version="2.16"> + <doc xml:space="preserve">Appends @unescaped to @string, escaping any characters that +are reserved in URIs using URI-style escape sequences.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="unescaped" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="reserved_chars_allowed" transfer-ownership="none"> + <doc xml:space="preserve">a string of reserved characters allowed + to be used, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="allow_utf8" transfer-ownership="none"> + <doc xml:space="preserve">set %TRUE if the escaped string may include UTF8 characters</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="append_vprintf" c:identifier="g_string_append_vprintf" version="2.14" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">the string format. See the printf() documentation</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">the list of arguments to insert in the output</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </method> + <method name="ascii_down" c:identifier="g_string_ascii_down"> + <doc xml:space="preserve">Converts all uppercase ASCII letters to lowercase ASCII letters.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">passed-in @string pointer, with all the + uppercase characters converted to lowercase in place, + with semantics that exactly match g_ascii_tolower().</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + </parameters> + </method> + <method name="ascii_up" c:identifier="g_string_ascii_up"> + <doc xml:space="preserve">Converts all lowercase ASCII letters to uppercase ASCII letters.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">passed-in @string pointer, with all the + lowercase characters converted to uppercase in place, + with semantics that exactly match g_ascii_toupper().</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + </parameters> + </method> + <method name="assign" c:identifier="g_string_assign"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the destination #GString. Its current contents + are destroyed.</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="rval" transfer-ownership="none"> + <doc xml:space="preserve">the string to copy into @string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="down" c:identifier="g_string_down" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">Converts a #GString to lowercase.</doc> + <doc-deprecated xml:space="preserve">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.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GString</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + </parameters> + </method> + <method name="equal" c:identifier="g_string_equal"> + <doc xml:space="preserve">Compares two strings for equality, returning %TRUE if they are equal. +For use with #GHashTable.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the strings are the same length and contain the + same bytes</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="v" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="const GString*"/> + </instance-parameter> + <parameter name="v2" transfer-ownership="none"> + <doc xml:space="preserve">another #GString</doc> + <type name="String" c:type="const GString*"/> + </parameter> + </parameters> + </method> + <method name="erase" c:identifier="g_string_erase"> + <doc xml:space="preserve">Removes @len bytes from a #GString, starting at position @pos. +The rest of the #GString is shifted down to fill the gap.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="pos" transfer-ownership="none"> + <doc xml:space="preserve">the position of the content to remove</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to remove, or -1 to remove all + following bytes</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </method> + <method name="free" c:identifier="g_string_free"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the character data of @string + (i.e. %NULL if @free_segment is %TRUE)</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="full"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="free_segment" transfer-ownership="none"> + <doc xml:space="preserve">if %TRUE, the actual character data is freed as well</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="free_to_bytes" c:identifier="g_string_free_to_bytes" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A newly allocated #GBytes containing contents of @string; @string itself is freed</doc> + <type name="Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="full"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + </parameters> + </method> + <method name="hash" c:identifier="g_string_hash"> + <doc xml:space="preserve">Creates a hash code for @str; for use with #GHashTable.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">hash code for @str</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a string to hash</doc> + <type name="String" c:type="const GString*"/> + </instance-parameter> + </parameters> + </method> + <method name="insert" c:identifier="g_string_insert"> + <doc xml:space="preserve">Inserts a copy of a string into a #GString, +expanding it if necessary.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="pos" transfer-ownership="none"> + <doc xml:space="preserve">the position to insert the copy of the string</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">the string to insert</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="insert_c" c:identifier="g_string_insert_c"> + <doc xml:space="preserve">Inserts a byte into a #GString, expanding it if necessary.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="pos" transfer-ownership="none"> + <doc xml:space="preserve">the position to insert the byte</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">the byte to insert</doc> + <type name="gchar" c:type="gchar"/> + </parameter> + </parameters> + </method> + <method name="insert_len" c:identifier="g_string_insert_len"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="pos" transfer-ownership="none"> + <doc xml:space="preserve">position in @string where insertion should + happen, or -1 for at the end</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">bytes to insert</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">number of bytes of @val to insert, or -1 for all of @val</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </method> + <method name="insert_unichar" c:identifier="g_string_insert_unichar"> + <doc xml:space="preserve">Converts a Unicode character into UTF-8, and insert it +into the string at the given position.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="pos" transfer-ownership="none"> + <doc xml:space="preserve">the position at which to insert character, or -1 + to append at the end of the string</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="wc" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </method> + <method name="overwrite" c:identifier="g_string_overwrite" version="2.14"> + <doc xml:space="preserve">Overwrites part of a string, lengthening it if necessary.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="pos" transfer-ownership="none"> + <doc xml:space="preserve">the position at which to start overwriting</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">the string that will overwrite the @string starting at @pos</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="overwrite_len" c:identifier="g_string_overwrite_len" version="2.14"> + <doc xml:space="preserve">Overwrites part of a string, lengthening it if necessary. +This function will work with embedded nuls.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="pos" transfer-ownership="none"> + <doc xml:space="preserve">the position at which to start overwriting</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">the string that will overwrite the @string starting at @pos</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to write from @val</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </method> + <method name="prepend" c:identifier="g_string_prepend"> + <doc xml:space="preserve">Adds a string on to the start of a #GString, +expanding it if necessary.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">the string to prepend on the start of @string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="prepend_c" c:identifier="g_string_prepend_c"> + <doc xml:space="preserve">Adds a byte onto the start of a #GString, +expanding it if necessary.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">the byte to prepend on the start of the #GString</doc> + <type name="gchar" c:type="gchar"/> + </parameter> + </parameters> + </method> + <method name="prepend_len" c:identifier="g_string_prepend_len"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">bytes to prepend</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">number of bytes in @val to prepend, or -1 for all of @val</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </method> + <method name="prepend_unichar" c:identifier="g_string_prepend_unichar"> + <doc xml:space="preserve">Converts a Unicode character into UTF-8, and prepends it +to the string.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="wc" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </method> + <method name="printf" c:identifier="g_string_printf" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">the string format. See the printf() documentation</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the parameters to insert into the format string</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="set_size" c:identifier="g_string_set_size"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the new length</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <method name="truncate" c:identifier="g_string_truncate"> + <doc xml:space="preserve">Cuts off the end of the GString, leaving the first @len bytes.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the new size of @string</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <method name="up" c:identifier="g_string_up" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">Converts a #GString to uppercase.</doc> + <doc-deprecated xml:space="preserve">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.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + </parameters> + </method> + <method name="vprintf" c:identifier="g_string_vprintf" version="2.14" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a #GString</doc> + <type name="String" c:type="GString*"/> + </instance-parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">the string format. See the printf() documentation</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">the parameters to insert into the format string</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </method> + </record> + <record name="StringChunk" c:type="GStringChunk" disguised="1"> + <doc xml:space="preserve">An opaque data structure representing String Chunks. +It should only be accessed by using the following functions.</doc> + <method name="clear" c:identifier="g_string_chunk_clear" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="chunk" transfer-ownership="none"> + <doc xml:space="preserve">a #GStringChunk</doc> + <type name="StringChunk" c:type="GStringChunk*"/> + </instance-parameter> + </parameters> + </method> + <method name="free" c:identifier="g_string_chunk_free"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="chunk" transfer-ownership="none"> + <doc xml:space="preserve">a #GStringChunk</doc> + <type name="StringChunk" c:type="GStringChunk*"/> + </instance-parameter> + </parameters> + </method> + <method name="insert" c:identifier="g_string_chunk_insert"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to the copy of @string within + the #GStringChunk</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="chunk" transfer-ownership="none"> + <doc xml:space="preserve">a #GStringChunk</doc> + <type name="StringChunk" c:type="GStringChunk*"/> + </instance-parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to add</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="insert_const" c:identifier="g_string_chunk_insert_const"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to the new or existing copy of @string + within the #GStringChunk</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="chunk" transfer-ownership="none"> + <doc xml:space="preserve">a #GStringChunk</doc> + <type name="StringChunk" c:type="GStringChunk*"/> + </instance-parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to add</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="insert_len" c:identifier="g_string_chunk_insert_len" version="2.4"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to the copy of @string within the #GStringChunk</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="chunk" transfer-ownership="none"> + <doc xml:space="preserve">a #GStringChunk</doc> + <type name="StringChunk" c:type="GStringChunk*"/> + </instance-parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">bytes to insert</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">number of bytes of @string to insert, or -1 to insert a + nul-terminated string</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </method> + <function name="new" c:identifier="g_string_chunk_new" introspectable="0"> + <doc xml:space="preserve">Creates a new #GStringChunk.</doc> + <return-value> + <doc xml:space="preserve">a new #GStringChunk</doc> + <type name="StringChunk" c:type="GStringChunk*"/> + </return-value> + <parameters> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + </record> + <constant name="TEST_OPTION_ISOLATE_DIRS" value="isolate_dirs" c:type="G_TEST_OPTION_ISOLATE_DIRS" version="2.60"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="TIME_SPAN_DAY" value="86400000000" c:type="G_TIME_SPAN_DAY" version="2.26"> + <doc xml:space="preserve">Evaluates to a time span of one day.</doc> + <type name="gint64" c:type="gint64"/> + </constant> + <constant name="TIME_SPAN_HOUR" value="3600000000" c:type="G_TIME_SPAN_HOUR" version="2.26"> + <doc xml:space="preserve">Evaluates to a time span of one hour.</doc> + <type name="gint64" c:type="gint64"/> + </constant> + <constant name="TIME_SPAN_MILLISECOND" value="1000" c:type="G_TIME_SPAN_MILLISECOND" version="2.26"> + <doc xml:space="preserve">Evaluates to a time span of one millisecond.</doc> + <type name="gint64" c:type="gint64"/> + </constant> + <constant name="TIME_SPAN_MINUTE" value="60000000" c:type="G_TIME_SPAN_MINUTE" version="2.26"> + <doc xml:space="preserve">Evaluates to a time span of one minute.</doc> + <type name="gint64" c:type="gint64"/> + </constant> + <constant name="TIME_SPAN_SECOND" value="1000000" c:type="G_TIME_SPAN_SECOND" version="2.26"> + <doc xml:space="preserve">Evaluates to a time span of one second.</doc> + <type name="gint64" c:type="gint64"/> + </constant> + <function-macro name="TRYLOCK" c:identifier="G_TRYLOCK" introspectable="0"> + <doc xml:space="preserve">Works like g_mutex_trylock(), but for a lock defined with +#G_LOCK_DEFINE.</doc> + <parameters> + <parameter name="name"> + <doc xml:space="preserve">the name of the lock</doc> + </parameter> + </parameters> + </function-macro> + <record name="TestCase" c:type="GTestCase" disguised="1"> + <doc xml:space="preserve">An opaque structure representing a test case.</doc> + </record> + <record name="TestConfig" c:type="GTestConfig"> + <field name="test_initialized" writable="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="test_quick" writable="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="test_perf" writable="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="test_verbose" writable="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="test_quiet" writable="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="test_undefined" writable="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + </record> + <callback name="TestDataFunc" c:type="GTestDataFunc" version="2.28"> + <doc xml:space="preserve">The type used for test case functions that take an extra pointer +argument.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="0"> + <doc xml:space="preserve">the data provided when registering the test</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </callback> + <enumeration name="TestFileType" version="2.38" c:type="GTestFileType"> + <doc xml:space="preserve">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.</doc> + <member name="dist" value="0" c:identifier="G_TEST_DIST"> + <doc xml:space="preserve">a file that was included in the distribution tarball</doc> + </member> + <member name="built" value="1" c:identifier="G_TEST_BUILT"> + <doc xml:space="preserve">a file that was built on the compiling machine</doc> + </member> + </enumeration> + <callback name="TestFixtureFunc" c:type="GTestFixtureFunc" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="fixture" transfer-ownership="none"> + <doc xml:space="preserve">the test fixture</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="1"> + <doc xml:space="preserve">the data provided when registering the test</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </callback> + <callback name="TestFunc" c:type="GTestFunc" version="2.28"> + <doc xml:space="preserve">The type used for test case functions.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + <record name="TestLogBuffer" c:type="GTestLogBuffer"> + <field name="data" readable="0" private="1"> + <type name="String" c:type="GString*"/> + </field> + <field name="msgs" readable="0" private="1"> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </field> + <method name="free" c:identifier="g_test_log_buffer_free"> + <doc xml:space="preserve">Internal function for gtester to free test log messages, no ABI guarantees provided.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="tbuffer" transfer-ownership="none"> + <type name="TestLogBuffer" c:type="GTestLogBuffer*"/> + </instance-parameter> + </parameters> + </method> + <method name="pop" c:identifier="g_test_log_buffer_pop" introspectable="0"> + <doc xml:space="preserve">Internal function for gtester to retrieve test log messages, no ABI guarantees provided.</doc> + <return-value> + <type name="TestLogMsg" c:type="GTestLogMsg*"/> + </return-value> + <parameters> + <instance-parameter name="tbuffer" transfer-ownership="none"> + <type name="TestLogBuffer" c:type="GTestLogBuffer*"/> + </instance-parameter> + </parameters> + </method> + <method name="push" c:identifier="g_test_log_buffer_push"> + <doc xml:space="preserve">Internal function for gtester to decode test log messages, no ABI guarantees provided.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="tbuffer" transfer-ownership="none"> + <type name="TestLogBuffer" c:type="GTestLogBuffer*"/> + </instance-parameter> + <parameter name="n_bytes" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="bytes" transfer-ownership="none"> + <type name="guint8" c:type="const guint8*"/> + </parameter> + </parameters> + </method> + <function name="new" c:identifier="g_test_log_buffer_new" introspectable="0"> + <doc xml:space="preserve">Internal function for gtester to decode test log messages, no ABI guarantees provided.</doc> + <return-value> + <type name="TestLogBuffer" c:type="GTestLogBuffer*"/> + </return-value> + </function> + </record> + <callback name="TestLogFatalFunc" c:type="GTestLogFatalFunc" version="2.22"> + <doc xml:space="preserve">Specifies the prototype of fatal log handler functions.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the program should abort, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="log_domain" transfer-ownership="none"> + <doc xml:space="preserve">the log domain of the message</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="log_level" transfer-ownership="none"> + <doc xml:space="preserve">the log level of the message (including the fatal and recursion flags)</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">the message to process</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">user data, set in g_test_log_set_fatal_handler()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="TestLogMsg" c:type="GTestLogMsg"> + <field name="log_type" writable="1"> + <type name="TestLogType" c:type="GTestLogType"/> + </field> + <field name="n_strings" writable="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="strings" writable="1"> + <type name="utf8" c:type="gchar**"/> + </field> + <field name="n_nums" writable="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="nums" introspectable="0" writable="1"> + <type name="long double" c:type="long double*"/> + </field> + <method name="free" c:identifier="g_test_log_msg_free"> + <doc xml:space="preserve">Internal function for gtester to free test log messages, no ABI guarantees provided.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="tmsg" transfer-ownership="none"> + <type name="TestLogMsg" c:type="GTestLogMsg*"/> + </instance-parameter> + </parameters> + </method> + </record> + <enumeration name="TestLogType" c:type="GTestLogType"> + <member name="none" value="0" c:identifier="G_TEST_LOG_NONE"> + </member> + <member name="error" value="1" c:identifier="G_TEST_LOG_ERROR"> + </member> + <member name="start_binary" value="2" c:identifier="G_TEST_LOG_START_BINARY"> + </member> + <member name="list_case" value="3" c:identifier="G_TEST_LOG_LIST_CASE"> + </member> + <member name="skip_case" value="4" c:identifier="G_TEST_LOG_SKIP_CASE"> + </member> + <member name="start_case" value="5" c:identifier="G_TEST_LOG_START_CASE"> + </member> + <member name="stop_case" value="6" c:identifier="G_TEST_LOG_STOP_CASE"> + </member> + <member name="min_result" value="7" c:identifier="G_TEST_LOG_MIN_RESULT"> + </member> + <member name="max_result" value="8" c:identifier="G_TEST_LOG_MAX_RESULT"> + </member> + <member name="message" value="9" c:identifier="G_TEST_LOG_MESSAGE"> + </member> + <member name="start_suite" value="10" c:identifier="G_TEST_LOG_START_SUITE"> + </member> + <member name="stop_suite" value="11" c:identifier="G_TEST_LOG_STOP_SUITE"> + </member> + </enumeration> + <enumeration name="TestResult" c:type="GTestResult"> + <member name="success" value="0" c:identifier="G_TEST_RUN_SUCCESS"> + </member> + <member name="skipped" value="1" c:identifier="G_TEST_RUN_SKIPPED"> + </member> + <member name="failure" value="2" c:identifier="G_TEST_RUN_FAILURE"> + </member> + <member name="incomplete" value="3" c:identifier="G_TEST_RUN_INCOMPLETE"> + </member> + </enumeration> + <bitfield name="TestSubprocessFlags" c:type="GTestSubprocessFlags"> + <doc xml:space="preserve">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.</doc> + <member name="stdin" value="1" c:identifier="G_TEST_SUBPROCESS_INHERIT_STDIN"> + <doc xml:space="preserve">If this flag is given, the child + process will inherit the parent's stdin. Otherwise, the child's + stdin is redirected to `/dev/null`.</doc> + </member> + <member name="stdout" value="2" c:identifier="G_TEST_SUBPROCESS_INHERIT_STDOUT"> + <doc xml:space="preserve">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().</doc> + </member> + <member name="stderr" value="4" c:identifier="G_TEST_SUBPROCESS_INHERIT_STDERR"> + <doc xml:space="preserve">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().</doc> + </member> + </bitfield> + <record name="TestSuite" c:type="GTestSuite" disguised="1"> + <doc xml:space="preserve">An opaque structure representing a test suite.</doc> + <method name="add" c:identifier="g_test_suite_add" version="2.16"> + <doc xml:space="preserve">Adds @test_case to @suite.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="suite" transfer-ownership="none"> + <doc xml:space="preserve">a #GTestSuite</doc> + <type name="TestSuite" c:type="GTestSuite*"/> + </instance-parameter> + <parameter name="test_case" transfer-ownership="none"> + <doc xml:space="preserve">a #GTestCase</doc> + <type name="TestCase" c:type="GTestCase*"/> + </parameter> + </parameters> + </method> + <method name="add_suite" c:identifier="g_test_suite_add_suite" version="2.16"> + <doc xml:space="preserve">Adds @nestedsuite to @suite.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="suite" transfer-ownership="none"> + <doc xml:space="preserve">a #GTestSuite</doc> + <type name="TestSuite" c:type="GTestSuite*"/> + </instance-parameter> + <parameter name="nestedsuite" transfer-ownership="none"> + <doc xml:space="preserve">another #GTestSuite</doc> + <type name="TestSuite" c:type="GTestSuite*"/> + </parameter> + </parameters> + </method> + </record> + <bitfield name="TestTrapFlags" deprecated="1" deprecated-version="2.38" c:type="GTestTrapFlags"> + <doc xml:space="preserve">Test traps are guards around forked tests. +These flags determine what traps to set.</doc> + <doc-deprecated xml:space="preserve">#GTestTrapFlags is used only with g_test_trap_fork(), +which is deprecated. g_test_trap_subprocess() uses +#GTestSubprocessFlags.</doc-deprecated> + <member name="silence_stdout" value="128" c:identifier="G_TEST_TRAP_SILENCE_STDOUT"> + <doc xml:space="preserve">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().</doc> + </member> + <member name="silence_stderr" value="256" c:identifier="G_TEST_TRAP_SILENCE_STDERR"> + <doc xml:space="preserve">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().</doc> + </member> + <member name="inherit_stdin" value="512" c:identifier="G_TEST_TRAP_INHERIT_STDIN"> + <doc xml:space="preserve">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.</doc> + </member> + </bitfield> + <record name="Thread" c:type="GThread" glib:type-name="GThread" glib:get-type="g_thread_get_type" c:symbol-prefix="thread"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_thread_new" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new #GThread</doc> + <type name="Thread" c:type="GThread*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an (optional) name for the new thread</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="func" transfer-ownership="none" scope="async" closure="2"> + <doc xml:space="preserve">a function to execute in the new thread</doc> + <type name="ThreadFunc" c:type="GThreadFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an argument to supply to the new thread</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </constructor> + <constructor name="try_new" c:identifier="g_thread_try_new" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new #GThread, or %NULL if an error occurred</doc> + <type name="Thread" c:type="GThread*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an (optional) name for the new thread</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="func" transfer-ownership="none" scope="async" closure="2"> + <doc xml:space="preserve">a function to execute in the new thread</doc> + <type name="ThreadFunc" c:type="GThreadFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an argument to supply to the new thread</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </constructor> + <method name="join" c:identifier="g_thread_join"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the return value of the thread</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="thread" transfer-ownership="full"> + <doc xml:space="preserve">a #GThread</doc> + <type name="Thread" c:type="GThread*"/> + </instance-parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_thread_ref" version="2.32"> + <doc xml:space="preserve">Increase the reference count on @thread.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new reference to @thread</doc> + <type name="Thread" c:type="GThread*"/> + </return-value> + <parameters> + <instance-parameter name="thread" transfer-ownership="none"> + <doc xml:space="preserve">a #GThread</doc> + <type name="Thread" c:type="GThread*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_thread_unref" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="thread" transfer-ownership="full"> + <doc xml:space="preserve">a #GThread</doc> + <type name="Thread" c:type="GThread*"/> + </instance-parameter> + </parameters> + </method> + <function name="error_quark" c:identifier="g_thread_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="exit" c:identifier="g_thread_exit"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="retval" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the return value of this thread</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="self" c:identifier="g_thread_self"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GThread representing the current thread</doc> + <type name="Thread" c:type="GThread*"/> + </return-value> + </function> + <function name="yield" c:identifier="g_thread_yield"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </function> + </record> + <enumeration name="ThreadError" c:type="GThreadError" glib:error-domain="g_thread_error"> + <doc xml:space="preserve">Possible errors of thread related functions.</doc> + <member name="thread_error_again" value="0" c:identifier="G_THREAD_ERROR_AGAIN"> + <doc xml:space="preserve">a thread couldn't be created due to resource + shortage. Try again later.</doc> + </member> + </enumeration> + <callback name="ThreadFunc" c:type="GThreadFunc"> + <doc xml:space="preserve">Specifies the type of the @func functions passed to g_thread_new() +or g_thread_try_new().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the return value of the thread</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data passed to the thread</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="ThreadPool" c:type="GThreadPool"> + <doc xml:space="preserve">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.</doc> + <field name="func" writable="1"> + <doc xml:space="preserve">the function to execute in the threads of this pool</doc> + <type name="Func" c:type="GFunc"/> + </field> + <field name="user_data" writable="1"> + <doc xml:space="preserve">the user data for the threads of this pool</doc> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="exclusive" writable="1"> + <doc xml:space="preserve">are all threads exclusive to this pool</doc> + <type name="gboolean" c:type="gboolean"/> + </field> + <method name="free" c:identifier="g_thread_pool_free"> + <doc xml:space="preserve">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, this function does not return before all +tasks to be processed (dependent on @immediate, whether all +or only the currently running) are ready. +Otherwise this function returns immediately. + +After calling this function @pool must not be used anymore.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="pool" transfer-ownership="none"> + <doc xml:space="preserve">a #GThreadPool</doc> + <type name="ThreadPool" c:type="GThreadPool*"/> + </instance-parameter> + <parameter name="immediate" transfer-ownership="none"> + <doc xml:space="preserve">should @pool shut down immediately?</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="wait_" transfer-ownership="none"> + <doc xml:space="preserve">should the function wait for all tasks to be finished?</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="get_max_threads" c:identifier="g_thread_pool_get_max_threads"> + <doc xml:space="preserve">Returns the maximal number of threads for @pool.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the maximal number of threads</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="pool" transfer-ownership="none"> + <doc xml:space="preserve">a #GThreadPool</doc> + <type name="ThreadPool" c:type="GThreadPool*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_num_threads" c:identifier="g_thread_pool_get_num_threads"> + <doc xml:space="preserve">Returns the number of threads currently running in @pool.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of threads currently running</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="pool" transfer-ownership="none"> + <doc xml:space="preserve">a #GThreadPool</doc> + <type name="ThreadPool" c:type="GThreadPool*"/> + </instance-parameter> + </parameters> + </method> + <method name="move_to_front" c:identifier="g_thread_pool_move_to_front" version="2.46"> + <doc xml:space="preserve">Moves the item to the front of the queue of unprocessed +items, so that it will be processed next.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the item was found and moved</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="pool" transfer-ownership="none"> + <doc xml:space="preserve">a #GThreadPool</doc> + <type name="ThreadPool" c:type="GThreadPool*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an unprocessed item in the pool</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="push" c:identifier="g_thread_pool_push" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if an error occurred</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="pool" transfer-ownership="none"> + <doc xml:space="preserve">a #GThreadPool</doc> + <type name="ThreadPool" c:type="GThreadPool*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a new task for @pool</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="set_max_threads" c:identifier="g_thread_pool_set_max_threads" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if an error occurred</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="pool" transfer-ownership="none"> + <doc xml:space="preserve">a #GThreadPool</doc> + <type name="ThreadPool" c:type="GThreadPool*"/> + </instance-parameter> + <parameter name="max_threads" transfer-ownership="none"> + <doc xml:space="preserve">a new maximal number of threads for @pool, + or -1 for unlimited</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="set_sort_function" c:identifier="g_thread_pool_set_sort_function" version="2.10" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="pool" transfer-ownership="none"> + <doc xml:space="preserve">a #GThreadPool</doc> + <type name="ThreadPool" c:type="GThreadPool*"/> + </instance-parameter> + <parameter name="func" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">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.</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="unprocessed" c:identifier="g_thread_pool_unprocessed"> + <doc xml:space="preserve">Returns the number of tasks still unprocessed in @pool.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of unprocessed tasks</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="pool" transfer-ownership="none"> + <doc xml:space="preserve">a #GThreadPool</doc> + <type name="ThreadPool" c:type="GThreadPool*"/> + </instance-parameter> + </parameters> + </method> + <function name="get_max_idle_time" c:identifier="g_thread_pool_get_max_idle_time" version="2.10"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the maximum @interval (milliseconds) to wait + for new tasks in the thread pool before stopping the + thread</doc> + <type name="guint" c:type="guint"/> + </return-value> + </function> + <function name="get_max_unused_threads" c:identifier="g_thread_pool_get_max_unused_threads"> + <doc xml:space="preserve">Returns the maximal allowed number of unused threads.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the maximal number of unused threads</doc> + <type name="gint" c:type="gint"/> + </return-value> + </function> + <function name="get_num_unused_threads" c:identifier="g_thread_pool_get_num_unused_threads"> + <doc xml:space="preserve">Returns the number of currently unused threads.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of currently unused threads</doc> + <type name="guint" c:type="guint"/> + </return-value> + </function> + <function name="new" c:identifier="g_thread_pool_new" introspectable="0" throws="1"> + <doc xml:space="preserve">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. + +Pass g_get_num_processors() to @max_threads to create as many threads as +there are logical processors on the system. This will not pin each thread to +a specific processor. + +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.</doc> + <return-value> + <doc xml:space="preserve">the new #GThreadPool</doc> + <type name="ThreadPool" c:type="GThreadPool*"/> + </return-value> + <parameters> + <parameter name="func" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">a function to execute in the threads of the new thread pool</doc> + <type name="Func" c:type="GFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data that is handed over to @func every time it + is called</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="max_threads" transfer-ownership="none"> + <doc xml:space="preserve">the maximal number of threads to execute concurrently + in the new thread pool, -1 means no limit</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="exclusive" transfer-ownership="none"> + <doc xml:space="preserve">should this thread pool be exclusive?</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="set_max_idle_time" c:identifier="g_thread_pool_set_max_idle_time" version="2.10"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="interval" transfer-ownership="none"> + <doc xml:space="preserve">the maximum @interval (in milliseconds) + a thread can be idle</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="set_max_unused_threads" c:identifier="g_thread_pool_set_max_unused_threads"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="max_threads" transfer-ownership="none"> + <doc xml:space="preserve">maximal number of unused threads</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="stop_unused_threads" c:identifier="g_thread_pool_stop_unused_threads"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </function> + </record> + <enumeration name="TimeType" c:type="GTimeType"> + <doc xml:space="preserve">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).</doc> + <member name="standard" value="0" c:identifier="G_TIME_TYPE_STANDARD"> + <doc xml:space="preserve">the time is in local standard time</doc> + </member> + <member name="daylight" value="1" c:identifier="G_TIME_TYPE_DAYLIGHT"> + <doc xml:space="preserve">the time is in local daylight time</doc> + </member> + <member name="universal" value="2" c:identifier="G_TIME_TYPE_UNIVERSAL"> + <doc xml:space="preserve">the time is in UTC</doc> + </member> + </enumeration> + <record name="TimeVal" c:type="GTimeVal" deprecated="1" deprecated-version="2.62"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use #GDateTime or #guint64 instead.</doc-deprecated> + <field name="tv_sec" writable="1"> + <doc xml:space="preserve">seconds</doc> + <type name="glong" c:type="glong"/> + </field> + <field name="tv_usec" writable="1"> + <doc xml:space="preserve">microseconds</doc> + <type name="glong" c:type="glong"/> + </field> + <method name="add" c:identifier="g_time_val_add" deprecated="1" deprecated-version="2.62"> + <doc xml:space="preserve">Adds the given number of microseconds to @time_. @microseconds can +also be negative to decrease the value of @time_.</doc> + <doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use `guint64` for + representing microseconds since the epoch, or use #GDateTime.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="time_" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeVal</doc> + <type name="TimeVal" c:type="GTimeVal*"/> + </instance-parameter> + <parameter name="microseconds" transfer-ownership="none"> + <doc xml:space="preserve">number of microseconds to add to @time</doc> + <type name="glong" c:type="glong"/> + </parameter> + </parameters> + </method> + <method name="to_iso8601" c:identifier="g_time_val_to_iso8601" version="2.12" deprecated="1" deprecated-version="2.62"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use + g_date_time_format_iso8601(dt) instead.</doc-deprecated> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly allocated string containing an ISO 8601 date, + or %NULL if @time_ was too large</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="time_" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeVal</doc> + <type name="TimeVal" c:type="GTimeVal*"/> + </instance-parameter> + </parameters> + </method> + <function name="from_iso8601" c:identifier="g_time_val_from_iso8601" version="2.12" deprecated="1" deprecated-version="2.62"> + <doc xml:space="preserve">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); +]|</doc> + <doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use + g_date_time_new_from_iso8601() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the conversion was successful.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="iso_date" transfer-ownership="none"> + <doc xml:space="preserve">an ISO 8601 encoded date string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="time_" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeVal</doc> + <type name="TimeVal" c:type="GTimeVal*"/> + </parameter> + </parameters> + </function> + </record> + <record name="TimeZone" c:type="GTimeZone" version="2.26" glib:type-name="GTimeZone" glib:get-type="g_time_zone_get_type" c:symbol-prefix="time_zone"> + <doc xml:space="preserve">#GTimeZone is an opaque structure whose members cannot be accessed +directly.</doc> + <constructor name="new" c:identifier="g_time_zone_new" version="2.26" deprecated="1" deprecated-version="2.68"> + <doc xml:space="preserve">A version of g_time_zone_new_identifier() which returns the UTC time zone +if @identifier could not be parsed or loaded. + +If you need to check whether @identifier was loaded successfully, use +g_time_zone_new_identifier().</doc> + <doc-deprecated xml:space="preserve">Use g_time_zone_new_identifier() instead, as it provides + error reporting. Change your code to handle a potentially %NULL return + value.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the requested timezone</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </return-value> + <parameters> + <parameter name="identifier" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a timezone identifier</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_local" c:identifier="g_time_zone_new_local" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the local timezone</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </return-value> + </constructor> + <constructor name="new_offset" c:identifier="g_time_zone_new_offset" version="2.58"> + <doc xml:space="preserve">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]]`.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a timezone at the given offset from UTC</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </return-value> + <parameters> + <parameter name="seconds" transfer-ownership="none"> + <doc xml:space="preserve">offset to UTC, in seconds</doc> + <type name="gint32" c:type="gint32"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_utc" c:identifier="g_time_zone_new_utc" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the universal timezone</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </return-value> + </constructor> + <method name="adjust_time" c:identifier="g_time_zone_adjust_time" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the interval containing @time_, never -1</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="tz" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeZone</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </instance-parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">the #GTimeType of @time_</doc> + <type name="TimeType" c:type="GTimeType"/> + </parameter> + <parameter name="time_" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a number of seconds since January 1, 1970</doc> + <type name="gint64" c:type="gint64*"/> + </parameter> + </parameters> + </method> + <method name="find_interval" c:identifier="g_time_zone_find_interval" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the interval containing @time_, or -1 in case of failure</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="tz" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeZone</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </instance-parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">the #GTimeType of @time_</doc> + <type name="TimeType" c:type="GTimeType"/> + </parameter> + <parameter name="time_" transfer-ownership="none"> + <doc xml:space="preserve">a number of seconds since January 1, 1970</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + </parameters> + </method> + <method name="get_abbreviation" c:identifier="g_time_zone_get_abbreviation" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the time zone abbreviation, which belongs to @tz</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="tz" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeZone</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </instance-parameter> + <parameter name="interval" transfer-ownership="none"> + <doc xml:space="preserve">an interval within the timezone</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="get_identifier" c:identifier="g_time_zone_get_identifier" version="2.58"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">identifier for this timezone</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="tz" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeZone</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_offset" c:identifier="g_time_zone_get_offset" version="2.26"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of seconds that should be added to UTC to get the + local time in @tz</doc> + <type name="gint32" c:type="gint32"/> + </return-value> + <parameters> + <instance-parameter name="tz" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeZone</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </instance-parameter> + <parameter name="interval" transfer-ownership="none"> + <doc xml:space="preserve">an interval within the timezone</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="is_dst" c:identifier="g_time_zone_is_dst" version="2.26"> + <doc xml:space="preserve">Determines if daylight savings time is in effect during a particular +@interval of time in the time zone @tz.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if daylight savings time is in effect</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="tz" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeZone</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </instance-parameter> + <parameter name="interval" transfer-ownership="none"> + <doc xml:space="preserve">an interval within the timezone</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_time_zone_ref" version="2.26"> + <doc xml:space="preserve">Increases the reference count on @tz.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new reference to @tz.</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </return-value> + <parameters> + <instance-parameter name="tz" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeZone</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_time_zone_unref" version="2.26"> + <doc xml:space="preserve">Decreases the reference count on @tz.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="tz" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeZone</doc> + <type name="TimeZone" c:type="GTimeZone*"/> + </instance-parameter> + </parameters> + </method> + </record> + <record name="Timer" c:type="GTimer" disguised="1"> + <doc xml:space="preserve">Opaque datatype that records a start time.</doc> + <method name="continue" c:identifier="g_timer_continue" version="2.4"> + <doc xml:space="preserve">Resumes a timer that has previously been stopped with +g_timer_stop(). g_timer_stop() must be called before using this +function.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="timer" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimer.</doc> + <type name="Timer" c:type="GTimer*"/> + </instance-parameter> + </parameters> + </method> + <method name="destroy" c:identifier="g_timer_destroy"> + <doc xml:space="preserve">Destroys a timer, freeing associated resources.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="timer" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimer to destroy.</doc> + <type name="Timer" c:type="GTimer*"/> + </instance-parameter> + </parameters> + </method> + <method name="elapsed" c:identifier="g_timer_elapsed"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">seconds elapsed as a floating point value, including any + fractional part.</doc> + <type name="gdouble" c:type="gdouble"/> + </return-value> + <parameters> + <instance-parameter name="timer" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimer.</doc> + <type name="Timer" c:type="GTimer*"/> + </instance-parameter> + <parameter name="microseconds" transfer-ownership="none"> + <doc xml:space="preserve">return location for the fractional part of seconds + elapsed, in microseconds (that is, the total number + of microseconds elapsed, modulo 1000000), or %NULL</doc> + <type name="gulong" c:type="gulong*"/> + </parameter> + </parameters> + </method> + <method name="is_active" c:identifier="g_timer_is_active" version="2.62"> + <doc xml:space="preserve">Exposes whether the timer is currently active.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the timer is running, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="timer" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimer.</doc> + <type name="Timer" c:type="GTimer*"/> + </instance-parameter> + </parameters> + </method> + <method name="reset" c:identifier="g_timer_reset"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="timer" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimer.</doc> + <type name="Timer" c:type="GTimer*"/> + </instance-parameter> + </parameters> + </method> + <method name="start" c:identifier="g_timer_start"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="timer" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimer.</doc> + <type name="Timer" c:type="GTimer*"/> + </instance-parameter> + </parameters> + </method> + <method name="stop" c:identifier="g_timer_stop"> + <doc xml:space="preserve">Marks an end time, so calls to g_timer_elapsed() will return the +difference between this end time and the start time.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="timer" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimer.</doc> + <type name="Timer" c:type="GTimer*"/> + </instance-parameter> + </parameters> + </method> + <function name="new" c:identifier="g_timer_new" introspectable="0"> + <doc xml:space="preserve">Creates a new timer, and starts timing (i.e. g_timer_start() is +implicitly called for you).</doc> + <return-value> + <doc xml:space="preserve">a new #GTimer.</doc> + <type name="Timer" c:type="GTimer*"/> + </return-value> + </function> + </record> + <enumeration name="TokenType" c:type="GTokenType"> + <doc xml:space="preserve">The possible types of token returned from each +g_scanner_get_next_token() call.</doc> + <member name="eof" value="0" c:identifier="G_TOKEN_EOF"> + <doc xml:space="preserve">the end of the file</doc> + </member> + <member name="left_paren" value="40" c:identifier="G_TOKEN_LEFT_PAREN"> + <doc xml:space="preserve">a '(' character</doc> + </member> + <member name="right_paren" value="41" c:identifier="G_TOKEN_RIGHT_PAREN"> + <doc xml:space="preserve">a ')' character</doc> + </member> + <member name="left_curly" value="123" c:identifier="G_TOKEN_LEFT_CURLY"> + <doc xml:space="preserve">a '{' character</doc> + </member> + <member name="right_curly" value="125" c:identifier="G_TOKEN_RIGHT_CURLY"> + <doc xml:space="preserve">a '}' character</doc> + </member> + <member name="left_brace" value="91" c:identifier="G_TOKEN_LEFT_BRACE"> + <doc xml:space="preserve">a '[' character</doc> + </member> + <member name="right_brace" value="93" c:identifier="G_TOKEN_RIGHT_BRACE"> + <doc xml:space="preserve">a ']' character</doc> + </member> + <member name="equal_sign" value="61" c:identifier="G_TOKEN_EQUAL_SIGN"> + <doc xml:space="preserve">a '=' character</doc> + </member> + <member name="comma" value="44" c:identifier="G_TOKEN_COMMA"> + <doc xml:space="preserve">a ',' character</doc> + </member> + <member name="none" value="256" c:identifier="G_TOKEN_NONE"> + <doc xml:space="preserve">not a token</doc> + </member> + <member name="error" value="257" c:identifier="G_TOKEN_ERROR"> + <doc xml:space="preserve">an error occurred</doc> + </member> + <member name="char" value="258" c:identifier="G_TOKEN_CHAR"> + <doc xml:space="preserve">a character</doc> + </member> + <member name="binary" value="259" c:identifier="G_TOKEN_BINARY"> + <doc xml:space="preserve">a binary integer</doc> + </member> + <member name="octal" value="260" c:identifier="G_TOKEN_OCTAL"> + <doc xml:space="preserve">an octal integer</doc> + </member> + <member name="int" value="261" c:identifier="G_TOKEN_INT"> + <doc xml:space="preserve">an integer</doc> + </member> + <member name="hex" value="262" c:identifier="G_TOKEN_HEX"> + <doc xml:space="preserve">a hex integer</doc> + </member> + <member name="float" value="263" c:identifier="G_TOKEN_FLOAT"> + <doc xml:space="preserve">a floating point number</doc> + </member> + <member name="string" value="264" c:identifier="G_TOKEN_STRING"> + <doc xml:space="preserve">a string</doc> + </member> + <member name="symbol" value="265" c:identifier="G_TOKEN_SYMBOL"> + <doc xml:space="preserve">a symbol</doc> + </member> + <member name="identifier" value="266" c:identifier="G_TOKEN_IDENTIFIER"> + <doc xml:space="preserve">an identifier</doc> + </member> + <member name="identifier_null" value="267" c:identifier="G_TOKEN_IDENTIFIER_NULL"> + <doc xml:space="preserve">a null identifier</doc> + </member> + <member name="comment_single" value="268" c:identifier="G_TOKEN_COMMENT_SINGLE"> + <doc xml:space="preserve">one line comment</doc> + </member> + <member name="comment_multi" value="269" c:identifier="G_TOKEN_COMMENT_MULTI"> + <doc xml:space="preserve">multi line comment</doc> + </member> + </enumeration> + <union name="TokenValue" c:type="GTokenValue"> + <doc xml:space="preserve">A union holding the value of the token.</doc> + <field name="v_symbol" writable="1"> + <doc xml:space="preserve">token symbol value</doc> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="v_identifier" writable="1"> + <doc xml:space="preserve">token identifier value</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="v_binary" writable="1"> + <doc xml:space="preserve">token binary integer value</doc> + <type name="gulong" c:type="gulong"/> + </field> + <field name="v_octal" writable="1"> + <doc xml:space="preserve">octal integer value</doc> + <type name="gulong" c:type="gulong"/> + </field> + <field name="v_int" writable="1"> + <doc xml:space="preserve">integer value</doc> + <type name="gulong" c:type="gulong"/> + </field> + <field name="v_int64" writable="1"> + <doc xml:space="preserve">64-bit integer value</doc> + <type name="guint64" c:type="guint64"/> + </field> + <field name="v_float" writable="1"> + <doc xml:space="preserve">floating point value</doc> + <type name="gdouble" c:type="gdouble"/> + </field> + <field name="v_hex" writable="1"> + <doc xml:space="preserve">hex integer value</doc> + <type name="gulong" c:type="gulong"/> + </field> + <field name="v_string" writable="1"> + <doc xml:space="preserve">string value</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="v_comment" writable="1"> + <doc xml:space="preserve">comment value</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="v_char" writable="1"> + <doc xml:space="preserve">character value</doc> + <type name="guint8" c:type="guchar"/> + </field> + <field name="v_error" writable="1"> + <doc xml:space="preserve">error value</doc> + <type name="guint" c:type="guint"/> + </field> + </union> + <callback name="TranslateFunc" c:type="GTranslateFunc"> + <doc xml:space="preserve">The type of functions which are used to translate user-visible +strings, for <option>--help</option> output.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a translation of the string for the current locale. + The returned string is owned by GLib and must not be freed.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">the untranslated string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data specified when installing the function, e.g. + in g_option_group_set_translate_func()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="TrashStack" c:type="GTrashStack" deprecated="1" deprecated-version="2.48"> + <doc xml:space="preserve">Each piece of memory that is pushed onto the stack +is cast to a GTrashStack*.</doc> + <doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated> + <field name="next" writable="1"> + <doc xml:space="preserve">pointer to the previous element of the stack, + gets stored in the first `sizeof (gpointer)` + bytes of the element</doc> + <type name="TrashStack" c:type="GTrashStack*"/> + </field> + <function name="height" c:identifier="g_trash_stack_height" deprecated="1" deprecated-version="2.48"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the height of the stack</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="stack_p" transfer-ownership="none"> + <doc xml:space="preserve">a #GTrashStack</doc> + <type name="TrashStack" c:type="GTrashStack**"/> + </parameter> + </parameters> + </function> + <function name="peek" c:identifier="g_trash_stack_peek" deprecated="1" deprecated-version="2.48"> + <doc xml:space="preserve">Returns the element at the top of a #GTrashStack +which may be %NULL.</doc> + <doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the element at the top of the stack</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="stack_p" transfer-ownership="none"> + <doc xml:space="preserve">a #GTrashStack</doc> + <type name="TrashStack" c:type="GTrashStack**"/> + </parameter> + </parameters> + </function> + <function name="pop" c:identifier="g_trash_stack_pop" deprecated="1" deprecated-version="2.48"> + <doc xml:space="preserve">Pops a piece of memory off a #GTrashStack.</doc> + <doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the element at the top of the stack</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="stack_p" transfer-ownership="none"> + <doc xml:space="preserve">a #GTrashStack</doc> + <type name="TrashStack" c:type="GTrashStack**"/> + </parameter> + </parameters> + </function> + <function name="push" c:identifier="g_trash_stack_push" deprecated="1" deprecated-version="2.48"> + <doc xml:space="preserve">Pushes a piece of memory onto a #GTrashStack.</doc> + <doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="stack_p" transfer-ownership="none"> + <doc xml:space="preserve">a #GTrashStack</doc> + <type name="TrashStack" c:type="GTrashStack**"/> + </parameter> + <parameter name="data_p" transfer-ownership="none"> + <doc xml:space="preserve">the piece of memory to push on the stack</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + </record> + <bitfield name="TraverseFlags" c:type="GTraverseFlags"> + <doc xml:space="preserve">Specifies which nodes are visited during several of the tree +functions, including g_node_traverse() and g_node_find().</doc> + <member name="leaves" value="1" c:identifier="G_TRAVERSE_LEAVES"> + <doc xml:space="preserve">only leaf nodes should be visited. This name has + been introduced in 2.6, for older version use + %G_TRAVERSE_LEAFS.</doc> + </member> + <member name="non_leaves" value="2" c:identifier="G_TRAVERSE_NON_LEAVES"> + <doc xml:space="preserve">only non-leaf nodes should be visited. This + name has been introduced in 2.6, for older + version use %G_TRAVERSE_NON_LEAFS.</doc> + </member> + <member name="all" value="3" c:identifier="G_TRAVERSE_ALL"> + <doc xml:space="preserve">all nodes should be visited.</doc> + </member> + <member name="mask" value="3" c:identifier="G_TRAVERSE_MASK"> + <doc xml:space="preserve">a mask of all traverse flags.</doc> + </member> + <member name="leafs" value="1" c:identifier="G_TRAVERSE_LEAFS"> + <doc xml:space="preserve">identical to %G_TRAVERSE_LEAVES.</doc> + </member> + <member name="non_leafs" value="2" c:identifier="G_TRAVERSE_NON_LEAFS"> + <doc xml:space="preserve">identical to %G_TRAVERSE_NON_LEAVES.</doc> + </member> + </bitfield> + <callback name="TraverseFunc" c:type="GTraverseFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop the traversal</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key of a #GTree node</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the value corresponding to the key</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to g_tree_traverse()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <enumeration name="TraverseType" c:type="GTraverseType"> + <doc xml:space="preserve">Specifies the type of traversal 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)</doc> + <member name="in_order" value="0" c:identifier="G_IN_ORDER"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="pre_order" value="1" c:identifier="G_PRE_ORDER"> + <doc xml:space="preserve">visits a node, then its children.</doc> + </member> + <member name="post_order" value="2" c:identifier="G_POST_ORDER"> + <doc xml:space="preserve">visits the node's children, then the node itself.</doc> + </member> + <member name="level_order" value="3" c:identifier="G_LEVEL_ORDER"> + <doc xml:space="preserve">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.</doc> + </member> + </enumeration> + <record name="Tree" c:type="GTree" disguised="1"> + <doc xml:space="preserve">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.</doc> + <method name="destroy" c:identifier="g_tree_destroy"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="tree" transfer-ownership="none"> + <doc xml:space="preserve">a #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </instance-parameter> + </parameters> + </method> + <method name="foreach" c:identifier="g_tree_foreach" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="tree" transfer-ownership="none"> + <doc xml:space="preserve">a #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </instance-parameter> + <parameter name="func" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">the function to call for each node visited. + If this function returns %TRUE, the traversal is stopped.</doc> + <type name="TraverseFunc" c:type="GTraverseFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to the function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="height" c:identifier="g_tree_height"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the height of @tree</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="tree" transfer-ownership="none"> + <doc xml:space="preserve">a #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </instance-parameter> + </parameters> + </method> + <method name="insert" c:identifier="g_tree_insert"> + <doc xml:space="preserve">Inserts a key/value pair into a #GTree. + +Inserts a new key and value into a #GTree as g_tree_insert_node() does, +only this function does not return the inserted or set node.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="tree" transfer-ownership="none"> + <doc xml:space="preserve">a #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the key to insert</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the value corresponding to the key</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="lookup" c:identifier="g_tree_lookup"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the value corresponding to the key, or %NULL + if the key was not found</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="tree" transfer-ownership="none"> + <doc xml:space="preserve">a #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the key to look up</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="lookup_extended" c:identifier="g_tree_lookup_extended"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key was found in the #GTree</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="tree" transfer-ownership="none"> + <doc xml:space="preserve">a #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </instance-parameter> + <parameter name="lookup_key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the key to look up</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="orig_key" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">returns the original key</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + <parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">returns the value associated with the key</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + </parameters> + </method> + <method name="nnodes" c:identifier="g_tree_nnodes"> + <doc xml:space="preserve">Gets the number of nodes in a #GTree.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of nodes in @tree</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="tree" transfer-ownership="none"> + <doc xml:space="preserve">a #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </instance-parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_tree_ref" version="2.22" introspectable="0"> + <doc xml:space="preserve">Increments the reference count of @tree by one. + +It is safe to call this function from any thread.</doc> + <return-value> + <doc xml:space="preserve">the passed in #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </return-value> + <parameters> + <instance-parameter name="tree" transfer-ownership="none"> + <doc xml:space="preserve">a #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </instance-parameter> + </parameters> + </method> + <method name="remove" c:identifier="g_tree_remove"> + <doc xml:space="preserve">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. + +The cost of maintaining a balanced tree while removing a key/value +result in a O(n log(n)) operation where most of the other operations +are O(log(n)).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key was found (prior to 2.8, this function + returned nothing)</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="tree" transfer-ownership="none"> + <doc xml:space="preserve">a #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the key to remove</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="replace" c:identifier="g_tree_replace"> + <doc xml:space="preserve">Inserts a new key and value into a #GTree as g_tree_replace_node() does, +only this function does not return the inserted or set node.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="tree" transfer-ownership="none"> + <doc xml:space="preserve">a #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the key to insert</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the value corresponding to the key</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="search" c:identifier="g_tree_search" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the value corresponding to the found key, or %NULL + if the key was not found</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="tree" transfer-ownership="none"> + <doc xml:space="preserve">a #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </instance-parameter> + <parameter name="search_func" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">a function used to search the #GTree</doc> + <type name="CompareFunc" c:type="GCompareFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data passed as the second argument to @search_func</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="steal" c:identifier="g_tree_steal"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key was found (prior to 2.8, this function + returned nothing)</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="tree" transfer-ownership="none"> + <doc xml:space="preserve">a #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the key to remove</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="traverse" c:identifier="g_tree_traverse" introspectable="0" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">Calls the given function for each node in the #GTree.</doc> + <doc-deprecated xml:space="preserve">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].</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="tree" transfer-ownership="none"> + <doc xml:space="preserve">a #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </instance-parameter> + <parameter name="traverse_func" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">the function to call for each node visited. If this + function returns %TRUE, the traversal is stopped.</doc> + <type name="TraverseFunc" c:type="GTraverseFunc"/> + </parameter> + <parameter name="traverse_type" transfer-ownership="none"> + <doc xml:space="preserve">the order in which nodes are visited, one of %G_IN_ORDER, + %G_PRE_ORDER and %G_POST_ORDER</doc> + <type name="TraverseType" c:type="GTraverseType"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to the function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_tree_unref" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="tree" transfer-ownership="none"> + <doc xml:space="preserve">a #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </instance-parameter> + </parameters> + </method> + <function name="new" c:identifier="g_tree_new" introspectable="0"> + <doc xml:space="preserve">Creates a new #GTree.</doc> + <return-value> + <doc xml:space="preserve">a newly allocated #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </return-value> + <parameters> + <parameter name="key_compare_func" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="CompareFunc" c:type="GCompareFunc"/> + </parameter> + </parameters> + </function> + <function name="new_full" c:identifier="g_tree_new_full" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">a newly allocated #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </return-value> + <parameters> + <parameter name="key_compare_func" transfer-ownership="none" scope="notified" closure="1" destroy="3"> + <doc xml:space="preserve">qsort()-style comparison function</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="key_compare_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to comparison function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="key_destroy_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">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</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + <parameter name="value_destroy_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">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</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="new_with_data" c:identifier="g_tree_new_with_data" introspectable="0"> + <doc xml:space="preserve">Creates a new #GTree with a comparison function that accepts user data. +See g_tree_new() for more details.</doc> + <return-value> + <doc xml:space="preserve">a newly allocated #GTree</doc> + <type name="Tree" c:type="GTree*"/> + </return-value> + <parameters> + <parameter name="key_compare_func" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">qsort()-style comparison function</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="key_compare_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to comparison function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + </record> + <function-macro name="UNAVAILABLE" c:identifier="G_UNAVAILABLE" version="2.32" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="maj"> + <doc xml:space="preserve">the major version that introduced the symbol</doc> + </parameter> + <parameter name="min"> + <doc xml:space="preserve">the minor version that introduced the symbol</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNAVAILABLE_ENUMERATOR" c:identifier="GLIB_UNAVAILABLE_ENUMERATOR" introspectable="0"> + <parameters> + <parameter name="maj"> + </parameter> + <parameter name="min"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNAVAILABLE_MACRO" c:identifier="GLIB_UNAVAILABLE_MACRO" introspectable="0"> + <parameters> + <parameter name="maj"> + </parameter> + <parameter name="min"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNAVAILABLE_STATIC_INLINE" c:identifier="GLIB_UNAVAILABLE_STATIC_INLINE" introspectable="0"> + <parameters> + <parameter name="maj"> + </parameter> + <parameter name="min"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNAVAILABLE_TYPE" c:identifier="GLIB_UNAVAILABLE_TYPE" introspectable="0"> + <parameters> + <parameter name="maj"> + </parameter> + <parameter name="min"> + </parameter> + </parameters> + </function-macro> + <constant name="UNICHAR_MAX_DECOMPOSITION_LENGTH" value="18" c:type="G_UNICHAR_MAX_DECOMPOSITION_LENGTH" version="2.32"> + <doc xml:space="preserve">The maximum length (in codepoints) of a compatibility or canonical +decomposition of a single Unicode character. + +This is as defined by Unicode 6.1.</doc> + <type name="gint" c:type="gint"/> + </constant> + <function-macro name="UNLIKELY" c:identifier="G_UNLIKELY" version="2.2" introspectable="0"> + <doc xml:space="preserve">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"); +]|</doc> + <parameters> + <parameter name="expr"> + <doc xml:space="preserve">the expression</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNLOCK" c:identifier="G_UNLOCK" introspectable="0"> + <doc xml:space="preserve">Works like g_mutex_unlock(), but for a lock defined with +#G_LOCK_DEFINE.</doc> + <parameters> + <parameter name="name"> + <doc xml:space="preserve">the name of the lock</doc> + </parameter> + </parameters> + </function-macro> + <constant name="URI_RESERVED_CHARS_GENERIC_DELIMITERS" value=":/?#[]@" c:type="G_URI_RESERVED_CHARS_GENERIC_DELIMITERS" version="2.16"> + <doc xml:space="preserve">Generic delimiters characters as defined in +[RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `:/?#[]@`.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS" value="!$&'()*+,;=" c:type="G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS" version="2.16"> + <doc xml:space="preserve">Subcomponent delimiter characters as defined in +[RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `!$&'()*+,;=`.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="USEC_PER_SEC" value="1000000" c:type="G_USEC_PER_SEC"> + <doc xml:space="preserve">Number of microseconds in one second (1 million). +This macro is provided for code readability.</doc> + <type name="gint" c:type="gint"/> + </constant> + <enumeration name="UnicodeBreakType" c:type="GUnicodeBreakType"> + <doc xml:space="preserve">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/).</doc> + <member name="mandatory" value="0" c:identifier="G_UNICODE_BREAK_MANDATORY"> + <doc xml:space="preserve">Mandatory Break (BK)</doc> + </member> + <member name="carriage_return" value="1" c:identifier="G_UNICODE_BREAK_CARRIAGE_RETURN"> + <doc xml:space="preserve">Carriage Return (CR)</doc> + </member> + <member name="line_feed" value="2" c:identifier="G_UNICODE_BREAK_LINE_FEED"> + <doc xml:space="preserve">Line Feed (LF)</doc> + </member> + <member name="combining_mark" value="3" c:identifier="G_UNICODE_BREAK_COMBINING_MARK"> + <doc xml:space="preserve">Attached Characters and Combining Marks (CM)</doc> + </member> + <member name="surrogate" value="4" c:identifier="G_UNICODE_BREAK_SURROGATE"> + <doc xml:space="preserve">Surrogates (SG)</doc> + </member> + <member name="zero_width_space" value="5" c:identifier="G_UNICODE_BREAK_ZERO_WIDTH_SPACE"> + <doc xml:space="preserve">Zero Width Space (ZW)</doc> + </member> + <member name="inseparable" value="6" c:identifier="G_UNICODE_BREAK_INSEPARABLE"> + <doc xml:space="preserve">Inseparable (IN)</doc> + </member> + <member name="non_breaking_glue" value="7" c:identifier="G_UNICODE_BREAK_NON_BREAKING_GLUE"> + <doc xml:space="preserve">Non-breaking ("Glue") (GL)</doc> + </member> + <member name="contingent" value="8" c:identifier="G_UNICODE_BREAK_CONTINGENT"> + <doc xml:space="preserve">Contingent Break Opportunity (CB)</doc> + </member> + <member name="space" value="9" c:identifier="G_UNICODE_BREAK_SPACE"> + <doc xml:space="preserve">Space (SP)</doc> + </member> + <member name="after" value="10" c:identifier="G_UNICODE_BREAK_AFTER"> + <doc xml:space="preserve">Break Opportunity After (BA)</doc> + </member> + <member name="before" value="11" c:identifier="G_UNICODE_BREAK_BEFORE"> + <doc xml:space="preserve">Break Opportunity Before (BB)</doc> + </member> + <member name="before_and_after" value="12" c:identifier="G_UNICODE_BREAK_BEFORE_AND_AFTER"> + <doc xml:space="preserve">Break Opportunity Before and After (B2)</doc> + </member> + <member name="hyphen" value="13" c:identifier="G_UNICODE_BREAK_HYPHEN"> + <doc xml:space="preserve">Hyphen (HY)</doc> + </member> + <member name="non_starter" value="14" c:identifier="G_UNICODE_BREAK_NON_STARTER"> + <doc xml:space="preserve">Nonstarter (NS)</doc> + </member> + <member name="open_punctuation" value="15" c:identifier="G_UNICODE_BREAK_OPEN_PUNCTUATION"> + <doc xml:space="preserve">Opening Punctuation (OP)</doc> + </member> + <member name="close_punctuation" value="16" c:identifier="G_UNICODE_BREAK_CLOSE_PUNCTUATION"> + <doc xml:space="preserve">Closing Punctuation (CL)</doc> + </member> + <member name="quotation" value="17" c:identifier="G_UNICODE_BREAK_QUOTATION"> + <doc xml:space="preserve">Ambiguous Quotation (QU)</doc> + </member> + <member name="exclamation" value="18" c:identifier="G_UNICODE_BREAK_EXCLAMATION"> + <doc xml:space="preserve">Exclamation/Interrogation (EX)</doc> + </member> + <member name="ideographic" value="19" c:identifier="G_UNICODE_BREAK_IDEOGRAPHIC"> + <doc xml:space="preserve">Ideographic (ID)</doc> + </member> + <member name="numeric" value="20" c:identifier="G_UNICODE_BREAK_NUMERIC"> + <doc xml:space="preserve">Numeric (NU)</doc> + </member> + <member name="infix_separator" value="21" c:identifier="G_UNICODE_BREAK_INFIX_SEPARATOR"> + <doc xml:space="preserve">Infix Separator (Numeric) (IS)</doc> + </member> + <member name="symbol" value="22" c:identifier="G_UNICODE_BREAK_SYMBOL"> + <doc xml:space="preserve">Symbols Allowing Break After (SY)</doc> + </member> + <member name="alphabetic" value="23" c:identifier="G_UNICODE_BREAK_ALPHABETIC"> + <doc xml:space="preserve">Ordinary Alphabetic and Symbol Characters (AL)</doc> + </member> + <member name="prefix" value="24" c:identifier="G_UNICODE_BREAK_PREFIX"> + <doc xml:space="preserve">Prefix (Numeric) (PR)</doc> + </member> + <member name="postfix" value="25" c:identifier="G_UNICODE_BREAK_POSTFIX"> + <doc xml:space="preserve">Postfix (Numeric) (PO)</doc> + </member> + <member name="complex_context" value="26" c:identifier="G_UNICODE_BREAK_COMPLEX_CONTEXT"> + <doc xml:space="preserve">Complex Content Dependent (South East Asian) (SA)</doc> + </member> + <member name="ambiguous" value="27" c:identifier="G_UNICODE_BREAK_AMBIGUOUS"> + <doc xml:space="preserve">Ambiguous (Alphabetic or Ideographic) (AI)</doc> + </member> + <member name="unknown" value="28" c:identifier="G_UNICODE_BREAK_UNKNOWN"> + <doc xml:space="preserve">Unknown (XX)</doc> + </member> + <member name="next_line" value="29" c:identifier="G_UNICODE_BREAK_NEXT_LINE"> + <doc xml:space="preserve">Next Line (NL)</doc> + </member> + <member name="word_joiner" value="30" c:identifier="G_UNICODE_BREAK_WORD_JOINER"> + <doc xml:space="preserve">Word Joiner (WJ)</doc> + </member> + <member name="hangul_l_jamo" value="31" c:identifier="G_UNICODE_BREAK_HANGUL_L_JAMO"> + <doc xml:space="preserve">Hangul L Jamo (JL)</doc> + </member> + <member name="hangul_v_jamo" value="32" c:identifier="G_UNICODE_BREAK_HANGUL_V_JAMO"> + <doc xml:space="preserve">Hangul V Jamo (JV)</doc> + </member> + <member name="hangul_t_jamo" value="33" c:identifier="G_UNICODE_BREAK_HANGUL_T_JAMO"> + <doc xml:space="preserve">Hangul T Jamo (JT)</doc> + </member> + <member name="hangul_lv_syllable" value="34" c:identifier="G_UNICODE_BREAK_HANGUL_LV_SYLLABLE"> + <doc xml:space="preserve">Hangul LV Syllable (H2)</doc> + </member> + <member name="hangul_lvt_syllable" value="35" c:identifier="G_UNICODE_BREAK_HANGUL_LVT_SYLLABLE"> + <doc xml:space="preserve">Hangul LVT Syllable (H3)</doc> + </member> + <member name="close_paranthesis" value="36" c:identifier="G_UNICODE_BREAK_CLOSE_PARANTHESIS"> + <doc xml:space="preserve">Closing Parenthesis (CP). Since 2.28</doc> + </member> + <member name="conditional_japanese_starter" value="37" c:identifier="G_UNICODE_BREAK_CONDITIONAL_JAPANESE_STARTER"> + <doc xml:space="preserve">Conditional Japanese Starter (CJ). Since: 2.32</doc> + </member> + <member name="hebrew_letter" value="38" c:identifier="G_UNICODE_BREAK_HEBREW_LETTER"> + <doc xml:space="preserve">Hebrew Letter (HL). Since: 2.32</doc> + </member> + <member name="regional_indicator" value="39" c:identifier="G_UNICODE_BREAK_REGIONAL_INDICATOR"> + <doc xml:space="preserve">Regional Indicator (RI). Since: 2.36</doc> + </member> + <member name="emoji_base" value="40" c:identifier="G_UNICODE_BREAK_EMOJI_BASE"> + <doc xml:space="preserve">Emoji Base (EB). Since: 2.50</doc> + </member> + <member name="emoji_modifier" value="41" c:identifier="G_UNICODE_BREAK_EMOJI_MODIFIER"> + <doc xml:space="preserve">Emoji Modifier (EM). Since: 2.50</doc> + </member> + <member name="zero_width_joiner" value="42" c:identifier="G_UNICODE_BREAK_ZERO_WIDTH_JOINER"> + <doc xml:space="preserve">Zero Width Joiner (ZWJ). Since: 2.50</doc> + </member> + </enumeration> + <enumeration name="UnicodeScript" c:type="GUnicodeScript"> + <doc xml:space="preserve">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/).</doc> + <member name="invalid_code" value="-1" c:identifier="G_UNICODE_SCRIPT_INVALID_CODE"> + <doc xml:space="preserve">a value never returned from g_unichar_get_script()</doc> + </member> + <member name="common" value="0" c:identifier="G_UNICODE_SCRIPT_COMMON"> + <doc xml:space="preserve">a character used by multiple different scripts</doc> + </member> + <member name="inherited" value="1" c:identifier="G_UNICODE_SCRIPT_INHERITED"> + <doc xml:space="preserve">a mark glyph that takes its script from the + base glyph to which it is attached</doc> + </member> + <member name="arabic" value="2" c:identifier="G_UNICODE_SCRIPT_ARABIC"> + <doc xml:space="preserve">Arabic</doc> + </member> + <member name="armenian" value="3" c:identifier="G_UNICODE_SCRIPT_ARMENIAN"> + <doc xml:space="preserve">Armenian</doc> + </member> + <member name="bengali" value="4" c:identifier="G_UNICODE_SCRIPT_BENGALI"> + <doc xml:space="preserve">Bengali</doc> + </member> + <member name="bopomofo" value="5" c:identifier="G_UNICODE_SCRIPT_BOPOMOFO"> + <doc xml:space="preserve">Bopomofo</doc> + </member> + <member name="cherokee" value="6" c:identifier="G_UNICODE_SCRIPT_CHEROKEE"> + <doc xml:space="preserve">Cherokee</doc> + </member> + <member name="coptic" value="7" c:identifier="G_UNICODE_SCRIPT_COPTIC"> + <doc xml:space="preserve">Coptic</doc> + </member> + <member name="cyrillic" value="8" c:identifier="G_UNICODE_SCRIPT_CYRILLIC"> + <doc xml:space="preserve">Cyrillic</doc> + </member> + <member name="deseret" value="9" c:identifier="G_UNICODE_SCRIPT_DESERET"> + <doc xml:space="preserve">Deseret</doc> + </member> + <member name="devanagari" value="10" c:identifier="G_UNICODE_SCRIPT_DEVANAGARI"> + <doc xml:space="preserve">Devanagari</doc> + </member> + <member name="ethiopic" value="11" c:identifier="G_UNICODE_SCRIPT_ETHIOPIC"> + <doc xml:space="preserve">Ethiopic</doc> + </member> + <member name="georgian" value="12" c:identifier="G_UNICODE_SCRIPT_GEORGIAN"> + <doc xml:space="preserve">Georgian</doc> + </member> + <member name="gothic" value="13" c:identifier="G_UNICODE_SCRIPT_GOTHIC"> + <doc xml:space="preserve">Gothic</doc> + </member> + <member name="greek" value="14" c:identifier="G_UNICODE_SCRIPT_GREEK"> + <doc xml:space="preserve">Greek</doc> + </member> + <member name="gujarati" value="15" c:identifier="G_UNICODE_SCRIPT_GUJARATI"> + <doc xml:space="preserve">Gujarati</doc> + </member> + <member name="gurmukhi" value="16" c:identifier="G_UNICODE_SCRIPT_GURMUKHI"> + <doc xml:space="preserve">Gurmukhi</doc> + </member> + <member name="han" value="17" c:identifier="G_UNICODE_SCRIPT_HAN"> + <doc xml:space="preserve">Han</doc> + </member> + <member name="hangul" value="18" c:identifier="G_UNICODE_SCRIPT_HANGUL"> + <doc xml:space="preserve">Hangul</doc> + </member> + <member name="hebrew" value="19" c:identifier="G_UNICODE_SCRIPT_HEBREW"> + <doc xml:space="preserve">Hebrew</doc> + </member> + <member name="hiragana" value="20" c:identifier="G_UNICODE_SCRIPT_HIRAGANA"> + <doc xml:space="preserve">Hiragana</doc> + </member> + <member name="kannada" value="21" c:identifier="G_UNICODE_SCRIPT_KANNADA"> + <doc xml:space="preserve">Kannada</doc> + </member> + <member name="katakana" value="22" c:identifier="G_UNICODE_SCRIPT_KATAKANA"> + <doc xml:space="preserve">Katakana</doc> + </member> + <member name="khmer" value="23" c:identifier="G_UNICODE_SCRIPT_KHMER"> + <doc xml:space="preserve">Khmer</doc> + </member> + <member name="lao" value="24" c:identifier="G_UNICODE_SCRIPT_LAO"> + <doc xml:space="preserve">Lao</doc> + </member> + <member name="latin" value="25" c:identifier="G_UNICODE_SCRIPT_LATIN"> + <doc xml:space="preserve">Latin</doc> + </member> + <member name="malayalam" value="26" c:identifier="G_UNICODE_SCRIPT_MALAYALAM"> + <doc xml:space="preserve">Malayalam</doc> + </member> + <member name="mongolian" value="27" c:identifier="G_UNICODE_SCRIPT_MONGOLIAN"> + <doc xml:space="preserve">Mongolian</doc> + </member> + <member name="myanmar" value="28" c:identifier="G_UNICODE_SCRIPT_MYANMAR"> + <doc xml:space="preserve">Myanmar</doc> + </member> + <member name="ogham" value="29" c:identifier="G_UNICODE_SCRIPT_OGHAM"> + <doc xml:space="preserve">Ogham</doc> + </member> + <member name="old_italic" value="30" c:identifier="G_UNICODE_SCRIPT_OLD_ITALIC"> + <doc xml:space="preserve">Old Italic</doc> + </member> + <member name="oriya" value="31" c:identifier="G_UNICODE_SCRIPT_ORIYA"> + <doc xml:space="preserve">Oriya</doc> + </member> + <member name="runic" value="32" c:identifier="G_UNICODE_SCRIPT_RUNIC"> + <doc xml:space="preserve">Runic</doc> + </member> + <member name="sinhala" value="33" c:identifier="G_UNICODE_SCRIPT_SINHALA"> + <doc xml:space="preserve">Sinhala</doc> + </member> + <member name="syriac" value="34" c:identifier="G_UNICODE_SCRIPT_SYRIAC"> + <doc xml:space="preserve">Syriac</doc> + </member> + <member name="tamil" value="35" c:identifier="G_UNICODE_SCRIPT_TAMIL"> + <doc xml:space="preserve">Tamil</doc> + </member> + <member name="telugu" value="36" c:identifier="G_UNICODE_SCRIPT_TELUGU"> + <doc xml:space="preserve">Telugu</doc> + </member> + <member name="thaana" value="37" c:identifier="G_UNICODE_SCRIPT_THAANA"> + <doc xml:space="preserve">Thaana</doc> + </member> + <member name="thai" value="38" c:identifier="G_UNICODE_SCRIPT_THAI"> + <doc xml:space="preserve">Thai</doc> + </member> + <member name="tibetan" value="39" c:identifier="G_UNICODE_SCRIPT_TIBETAN"> + <doc xml:space="preserve">Tibetan</doc> + </member> + <member name="canadian_aboriginal" value="40" c:identifier="G_UNICODE_SCRIPT_CANADIAN_ABORIGINAL"> + <doc xml:space="preserve">Canadian Aboriginal</doc> + </member> + <member name="yi" value="41" c:identifier="G_UNICODE_SCRIPT_YI"> + <doc xml:space="preserve">Yi</doc> + </member> + <member name="tagalog" value="42" c:identifier="G_UNICODE_SCRIPT_TAGALOG"> + <doc xml:space="preserve">Tagalog</doc> + </member> + <member name="hanunoo" value="43" c:identifier="G_UNICODE_SCRIPT_HANUNOO"> + <doc xml:space="preserve">Hanunoo</doc> + </member> + <member name="buhid" value="44" c:identifier="G_UNICODE_SCRIPT_BUHID"> + <doc xml:space="preserve">Buhid</doc> + </member> + <member name="tagbanwa" value="45" c:identifier="G_UNICODE_SCRIPT_TAGBANWA"> + <doc xml:space="preserve">Tagbanwa</doc> + </member> + <member name="braille" value="46" c:identifier="G_UNICODE_SCRIPT_BRAILLE"> + <doc xml:space="preserve">Braille</doc> + </member> + <member name="cypriot" value="47" c:identifier="G_UNICODE_SCRIPT_CYPRIOT"> + <doc xml:space="preserve">Cypriot</doc> + </member> + <member name="limbu" value="48" c:identifier="G_UNICODE_SCRIPT_LIMBU"> + <doc xml:space="preserve">Limbu</doc> + </member> + <member name="osmanya" value="49" c:identifier="G_UNICODE_SCRIPT_OSMANYA"> + <doc xml:space="preserve">Osmanya</doc> + </member> + <member name="shavian" value="50" c:identifier="G_UNICODE_SCRIPT_SHAVIAN"> + <doc xml:space="preserve">Shavian</doc> + </member> + <member name="linear_b" value="51" c:identifier="G_UNICODE_SCRIPT_LINEAR_B"> + <doc xml:space="preserve">Linear B</doc> + </member> + <member name="tai_le" value="52" c:identifier="G_UNICODE_SCRIPT_TAI_LE"> + <doc xml:space="preserve">Tai Le</doc> + </member> + <member name="ugaritic" value="53" c:identifier="G_UNICODE_SCRIPT_UGARITIC"> + <doc xml:space="preserve">Ugaritic</doc> + </member> + <member name="new_tai_lue" value="54" c:identifier="G_UNICODE_SCRIPT_NEW_TAI_LUE"> + <doc xml:space="preserve">New Tai Lue</doc> + </member> + <member name="buginese" value="55" c:identifier="G_UNICODE_SCRIPT_BUGINESE"> + <doc xml:space="preserve">Buginese</doc> + </member> + <member name="glagolitic" value="56" c:identifier="G_UNICODE_SCRIPT_GLAGOLITIC"> + <doc xml:space="preserve">Glagolitic</doc> + </member> + <member name="tifinagh" value="57" c:identifier="G_UNICODE_SCRIPT_TIFINAGH"> + <doc xml:space="preserve">Tifinagh</doc> + </member> + <member name="syloti_nagri" value="58" c:identifier="G_UNICODE_SCRIPT_SYLOTI_NAGRI"> + <doc xml:space="preserve">Syloti Nagri</doc> + </member> + <member name="old_persian" value="59" c:identifier="G_UNICODE_SCRIPT_OLD_PERSIAN"> + <doc xml:space="preserve">Old Persian</doc> + </member> + <member name="kharoshthi" value="60" c:identifier="G_UNICODE_SCRIPT_KHAROSHTHI"> + <doc xml:space="preserve">Kharoshthi</doc> + </member> + <member name="unknown" value="61" c:identifier="G_UNICODE_SCRIPT_UNKNOWN"> + <doc xml:space="preserve">an unassigned code point</doc> + </member> + <member name="balinese" value="62" c:identifier="G_UNICODE_SCRIPT_BALINESE"> + <doc xml:space="preserve">Balinese</doc> + </member> + <member name="cuneiform" value="63" c:identifier="G_UNICODE_SCRIPT_CUNEIFORM"> + <doc xml:space="preserve">Cuneiform</doc> + </member> + <member name="phoenician" value="64" c:identifier="G_UNICODE_SCRIPT_PHOENICIAN"> + <doc xml:space="preserve">Phoenician</doc> + </member> + <member name="phags_pa" value="65" c:identifier="G_UNICODE_SCRIPT_PHAGS_PA"> + <doc xml:space="preserve">Phags-pa</doc> + </member> + <member name="nko" value="66" c:identifier="G_UNICODE_SCRIPT_NKO"> + <doc xml:space="preserve">N'Ko</doc> + </member> + <member name="kayah_li" value="67" c:identifier="G_UNICODE_SCRIPT_KAYAH_LI"> + <doc xml:space="preserve">Kayah Li. Since 2.16.3</doc> + </member> + <member name="lepcha" value="68" c:identifier="G_UNICODE_SCRIPT_LEPCHA"> + <doc xml:space="preserve">Lepcha. Since 2.16.3</doc> + </member> + <member name="rejang" value="69" c:identifier="G_UNICODE_SCRIPT_REJANG"> + <doc xml:space="preserve">Rejang. Since 2.16.3</doc> + </member> + <member name="sundanese" value="70" c:identifier="G_UNICODE_SCRIPT_SUNDANESE"> + <doc xml:space="preserve">Sundanese. Since 2.16.3</doc> + </member> + <member name="saurashtra" value="71" c:identifier="G_UNICODE_SCRIPT_SAURASHTRA"> + <doc xml:space="preserve">Saurashtra. Since 2.16.3</doc> + </member> + <member name="cham" value="72" c:identifier="G_UNICODE_SCRIPT_CHAM"> + <doc xml:space="preserve">Cham. Since 2.16.3</doc> + </member> + <member name="ol_chiki" value="73" c:identifier="G_UNICODE_SCRIPT_OL_CHIKI"> + <doc xml:space="preserve">Ol Chiki. Since 2.16.3</doc> + </member> + <member name="vai" value="74" c:identifier="G_UNICODE_SCRIPT_VAI"> + <doc xml:space="preserve">Vai. Since 2.16.3</doc> + </member> + <member name="carian" value="75" c:identifier="G_UNICODE_SCRIPT_CARIAN"> + <doc xml:space="preserve">Carian. Since 2.16.3</doc> + </member> + <member name="lycian" value="76" c:identifier="G_UNICODE_SCRIPT_LYCIAN"> + <doc xml:space="preserve">Lycian. Since 2.16.3</doc> + </member> + <member name="lydian" value="77" c:identifier="G_UNICODE_SCRIPT_LYDIAN"> + <doc xml:space="preserve">Lydian. Since 2.16.3</doc> + </member> + <member name="avestan" value="78" c:identifier="G_UNICODE_SCRIPT_AVESTAN"> + <doc xml:space="preserve">Avestan. Since 2.26</doc> + </member> + <member name="bamum" value="79" c:identifier="G_UNICODE_SCRIPT_BAMUM"> + <doc xml:space="preserve">Bamum. Since 2.26</doc> + </member> + <member name="egyptian_hieroglyphs" value="80" c:identifier="G_UNICODE_SCRIPT_EGYPTIAN_HIEROGLYPHS"> + <doc xml:space="preserve">Egyptian Hieroglpyhs. Since 2.26</doc> + </member> + <member name="imperial_aramaic" value="81" c:identifier="G_UNICODE_SCRIPT_IMPERIAL_ARAMAIC"> + <doc xml:space="preserve">Imperial Aramaic. Since 2.26</doc> + </member> + <member name="inscriptional_pahlavi" value="82" c:identifier="G_UNICODE_SCRIPT_INSCRIPTIONAL_PAHLAVI"> + <doc xml:space="preserve">Inscriptional Pahlavi. Since 2.26</doc> + </member> + <member name="inscriptional_parthian" value="83" c:identifier="G_UNICODE_SCRIPT_INSCRIPTIONAL_PARTHIAN"> + <doc xml:space="preserve">Inscriptional Parthian. Since 2.26</doc> + </member> + <member name="javanese" value="84" c:identifier="G_UNICODE_SCRIPT_JAVANESE"> + <doc xml:space="preserve">Javanese. Since 2.26</doc> + </member> + <member name="kaithi" value="85" c:identifier="G_UNICODE_SCRIPT_KAITHI"> + <doc xml:space="preserve">Kaithi. Since 2.26</doc> + </member> + <member name="lisu" value="86" c:identifier="G_UNICODE_SCRIPT_LISU"> + <doc xml:space="preserve">Lisu. Since 2.26</doc> + </member> + <member name="meetei_mayek" value="87" c:identifier="G_UNICODE_SCRIPT_MEETEI_MAYEK"> + <doc xml:space="preserve">Meetei Mayek. Since 2.26</doc> + </member> + <member name="old_south_arabian" value="88" c:identifier="G_UNICODE_SCRIPT_OLD_SOUTH_ARABIAN"> + <doc xml:space="preserve">Old South Arabian. Since 2.26</doc> + </member> + <member name="old_turkic" value="89" c:identifier="G_UNICODE_SCRIPT_OLD_TURKIC"> + <doc xml:space="preserve">Old Turkic. Since 2.28</doc> + </member> + <member name="samaritan" value="90" c:identifier="G_UNICODE_SCRIPT_SAMARITAN"> + <doc xml:space="preserve">Samaritan. Since 2.26</doc> + </member> + <member name="tai_tham" value="91" c:identifier="G_UNICODE_SCRIPT_TAI_THAM"> + <doc xml:space="preserve">Tai Tham. Since 2.26</doc> + </member> + <member name="tai_viet" value="92" c:identifier="G_UNICODE_SCRIPT_TAI_VIET"> + <doc xml:space="preserve">Tai Viet. Since 2.26</doc> + </member> + <member name="batak" value="93" c:identifier="G_UNICODE_SCRIPT_BATAK"> + <doc xml:space="preserve">Batak. Since 2.28</doc> + </member> + <member name="brahmi" value="94" c:identifier="G_UNICODE_SCRIPT_BRAHMI"> + <doc xml:space="preserve">Brahmi. Since 2.28</doc> + </member> + <member name="mandaic" value="95" c:identifier="G_UNICODE_SCRIPT_MANDAIC"> + <doc xml:space="preserve">Mandaic. Since 2.28</doc> + </member> + <member name="chakma" value="96" c:identifier="G_UNICODE_SCRIPT_CHAKMA"> + <doc xml:space="preserve">Chakma. Since: 2.32</doc> + </member> + <member name="meroitic_cursive" value="97" c:identifier="G_UNICODE_SCRIPT_MEROITIC_CURSIVE"> + <doc xml:space="preserve">Meroitic Cursive. Since: 2.32</doc> + </member> + <member name="meroitic_hieroglyphs" value="98" c:identifier="G_UNICODE_SCRIPT_MEROITIC_HIEROGLYPHS"> + <doc xml:space="preserve">Meroitic Hieroglyphs. Since: 2.32</doc> + </member> + <member name="miao" value="99" c:identifier="G_UNICODE_SCRIPT_MIAO"> + <doc xml:space="preserve">Miao. Since: 2.32</doc> + </member> + <member name="sharada" value="100" c:identifier="G_UNICODE_SCRIPT_SHARADA"> + <doc xml:space="preserve">Sharada. Since: 2.32</doc> + </member> + <member name="sora_sompeng" value="101" c:identifier="G_UNICODE_SCRIPT_SORA_SOMPENG"> + <doc xml:space="preserve">Sora Sompeng. Since: 2.32</doc> + </member> + <member name="takri" value="102" c:identifier="G_UNICODE_SCRIPT_TAKRI"> + <doc xml:space="preserve">Takri. Since: 2.32</doc> + </member> + <member name="bassa_vah" value="103" c:identifier="G_UNICODE_SCRIPT_BASSA_VAH"> + <doc xml:space="preserve">Bassa. Since: 2.42</doc> + </member> + <member name="caucasian_albanian" value="104" c:identifier="G_UNICODE_SCRIPT_CAUCASIAN_ALBANIAN"> + <doc xml:space="preserve">Caucasian Albanian. Since: 2.42</doc> + </member> + <member name="duployan" value="105" c:identifier="G_UNICODE_SCRIPT_DUPLOYAN"> + <doc xml:space="preserve">Duployan. Since: 2.42</doc> + </member> + <member name="elbasan" value="106" c:identifier="G_UNICODE_SCRIPT_ELBASAN"> + <doc xml:space="preserve">Elbasan. Since: 2.42</doc> + </member> + <member name="grantha" value="107" c:identifier="G_UNICODE_SCRIPT_GRANTHA"> + <doc xml:space="preserve">Grantha. Since: 2.42</doc> + </member> + <member name="khojki" value="108" c:identifier="G_UNICODE_SCRIPT_KHOJKI"> + <doc xml:space="preserve">Kjohki. Since: 2.42</doc> + </member> + <member name="khudawadi" value="109" c:identifier="G_UNICODE_SCRIPT_KHUDAWADI"> + <doc xml:space="preserve">Khudawadi, Sindhi. Since: 2.42</doc> + </member> + <member name="linear_a" value="110" c:identifier="G_UNICODE_SCRIPT_LINEAR_A"> + <doc xml:space="preserve">Linear A. Since: 2.42</doc> + </member> + <member name="mahajani" value="111" c:identifier="G_UNICODE_SCRIPT_MAHAJANI"> + <doc xml:space="preserve">Mahajani. Since: 2.42</doc> + </member> + <member name="manichaean" value="112" c:identifier="G_UNICODE_SCRIPT_MANICHAEAN"> + <doc xml:space="preserve">Manichaean. Since: 2.42</doc> + </member> + <member name="mende_kikakui" value="113" c:identifier="G_UNICODE_SCRIPT_MENDE_KIKAKUI"> + <doc xml:space="preserve">Mende Kikakui. Since: 2.42</doc> + </member> + <member name="modi" value="114" c:identifier="G_UNICODE_SCRIPT_MODI"> + <doc xml:space="preserve">Modi. Since: 2.42</doc> + </member> + <member name="mro" value="115" c:identifier="G_UNICODE_SCRIPT_MRO"> + <doc xml:space="preserve">Mro. Since: 2.42</doc> + </member> + <member name="nabataean" value="116" c:identifier="G_UNICODE_SCRIPT_NABATAEAN"> + <doc xml:space="preserve">Nabataean. Since: 2.42</doc> + </member> + <member name="old_north_arabian" value="117" c:identifier="G_UNICODE_SCRIPT_OLD_NORTH_ARABIAN"> + <doc xml:space="preserve">Old North Arabian. Since: 2.42</doc> + </member> + <member name="old_permic" value="118" c:identifier="G_UNICODE_SCRIPT_OLD_PERMIC"> + <doc xml:space="preserve">Old Permic. Since: 2.42</doc> + </member> + <member name="pahawh_hmong" value="119" c:identifier="G_UNICODE_SCRIPT_PAHAWH_HMONG"> + <doc xml:space="preserve">Pahawh Hmong. Since: 2.42</doc> + </member> + <member name="palmyrene" value="120" c:identifier="G_UNICODE_SCRIPT_PALMYRENE"> + <doc xml:space="preserve">Palmyrene. Since: 2.42</doc> + </member> + <member name="pau_cin_hau" value="121" c:identifier="G_UNICODE_SCRIPT_PAU_CIN_HAU"> + <doc xml:space="preserve">Pau Cin Hau. Since: 2.42</doc> + </member> + <member name="psalter_pahlavi" value="122" c:identifier="G_UNICODE_SCRIPT_PSALTER_PAHLAVI"> + <doc xml:space="preserve">Psalter Pahlavi. Since: 2.42</doc> + </member> + <member name="siddham" value="123" c:identifier="G_UNICODE_SCRIPT_SIDDHAM"> + <doc xml:space="preserve">Siddham. Since: 2.42</doc> + </member> + <member name="tirhuta" value="124" c:identifier="G_UNICODE_SCRIPT_TIRHUTA"> + <doc xml:space="preserve">Tirhuta. Since: 2.42</doc> + </member> + <member name="warang_citi" value="125" c:identifier="G_UNICODE_SCRIPT_WARANG_CITI"> + <doc xml:space="preserve">Warang Citi. Since: 2.42</doc> + </member> + <member name="ahom" value="126" c:identifier="G_UNICODE_SCRIPT_AHOM"> + <doc xml:space="preserve">Ahom. Since: 2.48</doc> + </member> + <member name="anatolian_hieroglyphs" value="127" c:identifier="G_UNICODE_SCRIPT_ANATOLIAN_HIEROGLYPHS"> + <doc xml:space="preserve">Anatolian Hieroglyphs. Since: 2.48</doc> + </member> + <member name="hatran" value="128" c:identifier="G_UNICODE_SCRIPT_HATRAN"> + <doc xml:space="preserve">Hatran. Since: 2.48</doc> + </member> + <member name="multani" value="129" c:identifier="G_UNICODE_SCRIPT_MULTANI"> + <doc xml:space="preserve">Multani. Since: 2.48</doc> + </member> + <member name="old_hungarian" value="130" c:identifier="G_UNICODE_SCRIPT_OLD_HUNGARIAN"> + <doc xml:space="preserve">Old Hungarian. Since: 2.48</doc> + </member> + <member name="signwriting" value="131" c:identifier="G_UNICODE_SCRIPT_SIGNWRITING"> + <doc xml:space="preserve">Signwriting. Since: 2.48</doc> + </member> + <member name="adlam" value="132" c:identifier="G_UNICODE_SCRIPT_ADLAM"> + <doc xml:space="preserve">Adlam. Since: 2.50</doc> + </member> + <member name="bhaiksuki" value="133" c:identifier="G_UNICODE_SCRIPT_BHAIKSUKI"> + <doc xml:space="preserve">Bhaiksuki. Since: 2.50</doc> + </member> + <member name="marchen" value="134" c:identifier="G_UNICODE_SCRIPT_MARCHEN"> + <doc xml:space="preserve">Marchen. Since: 2.50</doc> + </member> + <member name="newa" value="135" c:identifier="G_UNICODE_SCRIPT_NEWA"> + <doc xml:space="preserve">Newa. Since: 2.50</doc> + </member> + <member name="osage" value="136" c:identifier="G_UNICODE_SCRIPT_OSAGE"> + <doc xml:space="preserve">Osage. Since: 2.50</doc> + </member> + <member name="tangut" value="137" c:identifier="G_UNICODE_SCRIPT_TANGUT"> + <doc xml:space="preserve">Tangut. Since: 2.50</doc> + </member> + <member name="masaram_gondi" value="138" c:identifier="G_UNICODE_SCRIPT_MASARAM_GONDI"> + <doc xml:space="preserve">Masaram Gondi. Since: 2.54</doc> + </member> + <member name="nushu" value="139" c:identifier="G_UNICODE_SCRIPT_NUSHU"> + <doc xml:space="preserve">Nushu. Since: 2.54</doc> + </member> + <member name="soyombo" value="140" c:identifier="G_UNICODE_SCRIPT_SOYOMBO"> + <doc xml:space="preserve">Soyombo. Since: 2.54</doc> + </member> + <member name="zanabazar_square" value="141" c:identifier="G_UNICODE_SCRIPT_ZANABAZAR_SQUARE"> + <doc xml:space="preserve">Zanabazar Square. Since: 2.54</doc> + </member> + <member name="dogra" value="142" c:identifier="G_UNICODE_SCRIPT_DOGRA"> + <doc xml:space="preserve">Dogra. Since: 2.58</doc> + </member> + <member name="gunjala_gondi" value="143" c:identifier="G_UNICODE_SCRIPT_GUNJALA_GONDI"> + <doc xml:space="preserve">Gunjala Gondi. Since: 2.58</doc> + </member> + <member name="hanifi_rohingya" value="144" c:identifier="G_UNICODE_SCRIPT_HANIFI_ROHINGYA"> + <doc xml:space="preserve">Hanifi Rohingya. Since: 2.58</doc> + </member> + <member name="makasar" value="145" c:identifier="G_UNICODE_SCRIPT_MAKASAR"> + <doc xml:space="preserve">Makasar. Since: 2.58</doc> + </member> + <member name="medefaidrin" value="146" c:identifier="G_UNICODE_SCRIPT_MEDEFAIDRIN"> + <doc xml:space="preserve">Medefaidrin. Since: 2.58</doc> + </member> + <member name="old_sogdian" value="147" c:identifier="G_UNICODE_SCRIPT_OLD_SOGDIAN"> + <doc xml:space="preserve">Old Sogdian. Since: 2.58</doc> + </member> + <member name="sogdian" value="148" c:identifier="G_UNICODE_SCRIPT_SOGDIAN"> + <doc xml:space="preserve">Sogdian. Since: 2.58</doc> + </member> + <member name="elymaic" value="149" c:identifier="G_UNICODE_SCRIPT_ELYMAIC"> + <doc xml:space="preserve">Elym. Since: 2.62</doc> + </member> + <member name="nandinagari" value="150" c:identifier="G_UNICODE_SCRIPT_NANDINAGARI"> + <doc xml:space="preserve">Nand. Since: 2.62</doc> + </member> + <member name="nyiakeng_puachue_hmong" value="151" c:identifier="G_UNICODE_SCRIPT_NYIAKENG_PUACHUE_HMONG"> + <doc xml:space="preserve">Rohg. Since: 2.62</doc> + </member> + <member name="wancho" value="152" c:identifier="G_UNICODE_SCRIPT_WANCHO"> + <doc xml:space="preserve">Wcho. Since: 2.62</doc> + </member> + <member name="chorasmian" value="153" c:identifier="G_UNICODE_SCRIPT_CHORASMIAN"> + <doc xml:space="preserve">Chorasmian. Since: 2.66</doc> + </member> + <member name="dives_akuru" value="154" c:identifier="G_UNICODE_SCRIPT_DIVES_AKURU"> + <doc xml:space="preserve">Dives Akuru. Since: 2.66</doc> + </member> + <member name="khitan_small_script" value="155" c:identifier="G_UNICODE_SCRIPT_KHITAN_SMALL_SCRIPT"> + <doc xml:space="preserve">Khitan small script. Since: 2.66</doc> + </member> + <member name="yezidi" value="156" c:identifier="G_UNICODE_SCRIPT_YEZIDI"> + <doc xml:space="preserve">Yezidi. Since: 2.66</doc> + </member> + </enumeration> + <enumeration name="UnicodeType" c:type="GUnicodeType"> + <doc xml:space="preserve">These are the possible character classifications from the +Unicode specification. +See [Unicode Character Database](http://www.unicode.org/reports/tr44/#General_Category_Values).</doc> + <member name="control" value="0" c:identifier="G_UNICODE_CONTROL"> + <doc xml:space="preserve">General category "Other, Control" (Cc)</doc> + </member> + <member name="format" value="1" c:identifier="G_UNICODE_FORMAT"> + <doc xml:space="preserve">General category "Other, Format" (Cf)</doc> + </member> + <member name="unassigned" value="2" c:identifier="G_UNICODE_UNASSIGNED"> + <doc xml:space="preserve">General category "Other, Not Assigned" (Cn)</doc> + </member> + <member name="private_use" value="3" c:identifier="G_UNICODE_PRIVATE_USE"> + <doc xml:space="preserve">General category "Other, Private Use" (Co)</doc> + </member> + <member name="surrogate" value="4" c:identifier="G_UNICODE_SURROGATE"> + <doc xml:space="preserve">General category "Other, Surrogate" (Cs)</doc> + </member> + <member name="lowercase_letter" value="5" c:identifier="G_UNICODE_LOWERCASE_LETTER"> + <doc xml:space="preserve">General category "Letter, Lowercase" (Ll)</doc> + </member> + <member name="modifier_letter" value="6" c:identifier="G_UNICODE_MODIFIER_LETTER"> + <doc xml:space="preserve">General category "Letter, Modifier" (Lm)</doc> + </member> + <member name="other_letter" value="7" c:identifier="G_UNICODE_OTHER_LETTER"> + <doc xml:space="preserve">General category "Letter, Other" (Lo)</doc> + </member> + <member name="titlecase_letter" value="8" c:identifier="G_UNICODE_TITLECASE_LETTER"> + <doc xml:space="preserve">General category "Letter, Titlecase" (Lt)</doc> + </member> + <member name="uppercase_letter" value="9" c:identifier="G_UNICODE_UPPERCASE_LETTER"> + <doc xml:space="preserve">General category "Letter, Uppercase" (Lu)</doc> + </member> + <member name="spacing_mark" value="10" c:identifier="G_UNICODE_SPACING_MARK"> + <doc xml:space="preserve">General category "Mark, Spacing" (Mc)</doc> + </member> + <member name="enclosing_mark" value="11" c:identifier="G_UNICODE_ENCLOSING_MARK"> + <doc xml:space="preserve">General category "Mark, Enclosing" (Me)</doc> + </member> + <member name="non_spacing_mark" value="12" c:identifier="G_UNICODE_NON_SPACING_MARK"> + <doc xml:space="preserve">General category "Mark, Nonspacing" (Mn)</doc> + </member> + <member name="decimal_number" value="13" c:identifier="G_UNICODE_DECIMAL_NUMBER"> + <doc xml:space="preserve">General category "Number, Decimal Digit" (Nd)</doc> + </member> + <member name="letter_number" value="14" c:identifier="G_UNICODE_LETTER_NUMBER"> + <doc xml:space="preserve">General category "Number, Letter" (Nl)</doc> + </member> + <member name="other_number" value="15" c:identifier="G_UNICODE_OTHER_NUMBER"> + <doc xml:space="preserve">General category "Number, Other" (No)</doc> + </member> + <member name="connect_punctuation" value="16" c:identifier="G_UNICODE_CONNECT_PUNCTUATION"> + <doc xml:space="preserve">General category "Punctuation, Connector" (Pc)</doc> + </member> + <member name="dash_punctuation" value="17" c:identifier="G_UNICODE_DASH_PUNCTUATION"> + <doc xml:space="preserve">General category "Punctuation, Dash" (Pd)</doc> + </member> + <member name="close_punctuation" value="18" c:identifier="G_UNICODE_CLOSE_PUNCTUATION"> + <doc xml:space="preserve">General category "Punctuation, Close" (Pe)</doc> + </member> + <member name="final_punctuation" value="19" c:identifier="G_UNICODE_FINAL_PUNCTUATION"> + <doc xml:space="preserve">General category "Punctuation, Final quote" (Pf)</doc> + </member> + <member name="initial_punctuation" value="20" c:identifier="G_UNICODE_INITIAL_PUNCTUATION"> + <doc xml:space="preserve">General category "Punctuation, Initial quote" (Pi)</doc> + </member> + <member name="other_punctuation" value="21" c:identifier="G_UNICODE_OTHER_PUNCTUATION"> + <doc xml:space="preserve">General category "Punctuation, Other" (Po)</doc> + </member> + <member name="open_punctuation" value="22" c:identifier="G_UNICODE_OPEN_PUNCTUATION"> + <doc xml:space="preserve">General category "Punctuation, Open" (Ps)</doc> + </member> + <member name="currency_symbol" value="23" c:identifier="G_UNICODE_CURRENCY_SYMBOL"> + <doc xml:space="preserve">General category "Symbol, Currency" (Sc)</doc> + </member> + <member name="modifier_symbol" value="24" c:identifier="G_UNICODE_MODIFIER_SYMBOL"> + <doc xml:space="preserve">General category "Symbol, Modifier" (Sk)</doc> + </member> + <member name="math_symbol" value="25" c:identifier="G_UNICODE_MATH_SYMBOL"> + <doc xml:space="preserve">General category "Symbol, Math" (Sm)</doc> + </member> + <member name="other_symbol" value="26" c:identifier="G_UNICODE_OTHER_SYMBOL"> + <doc xml:space="preserve">General category "Symbol, Other" (So)</doc> + </member> + <member name="line_separator" value="27" c:identifier="G_UNICODE_LINE_SEPARATOR"> + <doc xml:space="preserve">General category "Separator, Line" (Zl)</doc> + </member> + <member name="paragraph_separator" value="28" c:identifier="G_UNICODE_PARAGRAPH_SEPARATOR"> + <doc xml:space="preserve">General category "Separator, Paragraph" (Zp)</doc> + </member> + <member name="space_separator" value="29" c:identifier="G_UNICODE_SPACE_SEPARATOR"> + <doc xml:space="preserve">General category "Separator, Space" (Zs)</doc> + </member> + </enumeration> + <callback name="UnixFDSourceFunc" c:type="GUnixFDSourceFunc"> + <doc xml:space="preserve">The type of functions to be called when a UNIX fd watch source +triggers.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%FALSE if the source should be removed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">the fd that triggered the event</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">the IO conditions reported on @fd</doc> + <type name="IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">user data passed to g_unix_fd_add()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="Uri" c:type="GUri" version="2.66" glib:type-name="GUri" glib:get-type="g_uri_get_type" c:symbol-prefix="uri"> + <doc xml:space="preserve">The #GUri type and related functions can be used to parse URIs into +their components, and build valid URIs from individual components. + +Note that #GUri scope is to help manipulate URIs in various applications, +following [RFC 3986](https://tools.ietf.org/html/rfc3986). In particular, +it doesn't intend to cover web browser needs, and doesn't implement the +[WHATWG URL](https://url.spec.whatwg.org/) standard. No APIs are provided to +help prevent +[homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), so +#GUri is not suitable for formatting URIs for display to the user for making +security-sensitive decisions. + +## Relative and absolute URIs # {#relative-absolute-uris} + +As defined in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4), the +hierarchical nature of URIs means that they can either be ‘relative +references’ (sometimes referred to as ‘relative URIs’) or ‘URIs’ (for +clarity, ‘URIs’ are referred to in this documentation as +‘absolute URIs’ — although +[in constrast to RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.3), +fragment identifiers are always allowed). + +Relative references have one or more components of the URI missing. In +particular, they have no scheme. Any other component, such as hostname, +query, etc. may be missing, apart from a path, which has to be specified (but +may be empty). The path may be relative, starting with `./` rather than `/`. + +For example, a valid relative reference is `./path?query`, +`/?query#fragment` or `//example.com`. + +Absolute URIs have a scheme specified. Any other components of the URI which +are missing are specified as explicitly unset in the URI, rather than being +resolved relative to a base URI using g_uri_parse_relative(). + +For example, a valid absolute URI is `file:///home/bob` or +`https://search.com?query=string`. + +A #GUri instance is always an absolute URI. A string may be an absolute URI +or a relative reference; see the documentation for individual functions as to +what forms they accept. + +## Parsing URIs + +The most minimalist APIs for parsing URIs are g_uri_split() and +g_uri_split_with_user(). These split a URI into its component +parts, and return the parts; the difference between the two is that +g_uri_split() treats the ‘userinfo’ component of the URI as a +single element, while g_uri_split_with_user() can (depending on the +#GUriFlags you pass) treat it as containing a username, password, +and authentication parameters. Alternatively, g_uri_split_network() +can be used when you are only interested in the components that are +needed to initiate a network connection to the service (scheme, +host, and port). + +g_uri_parse() is similar to g_uri_split(), but instead of returning +individual strings, it returns a #GUri structure (and it requires +that the URI be an absolute URI). + +g_uri_resolve_relative() and g_uri_parse_relative() allow you to +resolve a relative URI relative to a base URI. +g_uri_resolve_relative() takes two strings and returns a string, +and g_uri_parse_relative() takes a #GUri and a string and returns a +#GUri. + +All of the parsing functions take a #GUriFlags argument describing +exactly how to parse the URI; see the documentation for that type +for more details on the specific flags that you can pass. If you +need to choose different flags based on the type of URI, you can +use g_uri_peek_scheme() on the URI string to check the scheme +first, and use that to decide what flags to parse it with. + +For example, you might want to use %G_URI_PARAMS_WWW_FORM when parsing the +params for a web URI, so compare the result of g_uri_peek_scheme() against +`http` and `https`. + +## Building URIs + +g_uri_join() and g_uri_join_with_user() can be used to construct +valid URI strings from a set of component strings. They are the +inverse of g_uri_split() and g_uri_split_with_user(). + +Similarly, g_uri_build() and g_uri_build_with_user() can be used to +construct a #GUri from a set of component strings. + +As with the parsing functions, the building functions take a +#GUriFlags argument. In particular, it is important to keep in mind +whether the URI components you are using are already `%`-encoded. If so, +you must pass the %G_URI_FLAGS_ENCODED flag. + +## `file://` URIs + +Note that Windows and Unix both define special rules for parsing +`file://` URIs (involving non-UTF-8 character sets on Unix, and the +interpretation of path separators on Windows). #GUri does not +implement these rules. Use g_filename_from_uri() and +g_filename_to_uri() if you want to properly convert between +`file://` URIs and local filenames. + +## URI Equality + +Note that there is no `g_uri_equal ()` function, because comparing +URIs usefully requires scheme-specific knowledge that #GUri does +not have. #GUri can help with normalization if you use the various +encoded #GUriFlags as well as %G_URI_FLAGS_SCHEME_NORMALIZE however +it is not comprehensive. +For example, `data:,foo` and `data:;base64,Zm9v` resolve to the same +thing according to the `data:` URI specification which GLib does not +handle.</doc> + <method name="get_auth_params" c:identifier="g_uri_get_auth_params" version="2.66"> + <doc xml:space="preserve">Gets @uri's authentication parameters, which may contain +`%`-encoding, depending on the flags with which @uri was created. +(If @uri was not created with %G_URI_FLAGS_HAS_AUTH_PARAMS then this will +be %NULL.) + +Depending on the URI scheme, g_uri_parse_params() may be useful for +further parsing this information.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">@uri's authentication parameters.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_flags" c:identifier="g_uri_get_flags" version="2.66"> + <doc xml:space="preserve">Gets @uri's flags set upon construction.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@uri's flags.</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </return-value> + <parameters> + <instance-parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_fragment" c:identifier="g_uri_get_fragment" version="2.66"> + <doc xml:space="preserve">Gets @uri's fragment, which may contain `%`-encoding, depending on +the flags with which @uri was created.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">@uri's fragment.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_host" c:identifier="g_uri_get_host" version="2.66"> + <doc xml:space="preserve">Gets @uri's host. This will never have `%`-encoded characters, +unless it is non-UTF-8 (which can only be the case if @uri was +created with %G_URI_FLAGS_NON_DNS). + +If @uri contained an IPv6 address literal, this value will be just +that address, without the brackets around it that are necessary in +the string form of the URI. Note that in this case there may also +be a scope ID attached to the address. Eg, `fe80::1234%``em1` (or +`fe80::1234%``25em1` if the string is still encoded).</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">@uri's host.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_password" c:identifier="g_uri_get_password" version="2.66"> + <doc xml:space="preserve">Gets @uri's password, which may contain `%`-encoding, depending on +the flags with which @uri was created. (If @uri was not created +with %G_URI_FLAGS_HAS_PASSWORD then this will be %NULL.)</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">@uri's password.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_path" c:identifier="g_uri_get_path" version="2.66"> + <doc xml:space="preserve">Gets @uri's path, which may contain `%`-encoding, depending on the +flags with which @uri was created.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@uri's path.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_port" c:identifier="g_uri_get_port" version="2.66"> + <doc xml:space="preserve">Gets @uri's port.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@uri's port, or `-1` if no port was specified.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_query" c:identifier="g_uri_get_query" version="2.66"> + <doc xml:space="preserve">Gets @uri's query, which may contain `%`-encoding, depending on the +flags with which @uri was created. + +For queries consisting of a series of `name=value` parameters, +#GUriParamsIter or g_uri_parse_params() may be useful.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">@uri's query.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_scheme" c:identifier="g_uri_get_scheme" version="2.66"> + <doc xml:space="preserve">Gets @uri's scheme. Note that this will always be all-lowercase, +regardless of the string or strings that @uri was created from.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@uri's scheme.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_user" c:identifier="g_uri_get_user" version="2.66"> + <doc xml:space="preserve">Gets the ‘username’ component of @uri's userinfo, which may contain +`%`-encoding, depending on the flags with which @uri was created. +If @uri was not created with %G_URI_FLAGS_HAS_PASSWORD or +%G_URI_FLAGS_HAS_AUTH_PARAMS, this is the same as g_uri_get_userinfo().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">@uri's user.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_userinfo" c:identifier="g_uri_get_userinfo" version="2.66"> + <doc xml:space="preserve">Gets @uri's userinfo, which may contain `%`-encoding, depending on +the flags with which @uri was created.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">@uri's userinfo.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </instance-parameter> + </parameters> + </method> + <method name="parse_relative" c:identifier="g_uri_parse_relative" version="2.66" throws="1"> + <doc xml:space="preserve">Parses @uri_ref according to @flags and, if it is a +[relative URI][relative-absolute-uris], resolves it relative to @base_uri. +If the result is not a valid absolute URI, it will be discarded, and an error +returned.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUri, or NULL on error.</doc> + <type name="Uri" c:type="GUri*"/> + </return-value> + <parameters> + <instance-parameter name="base_uri" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a base absolute URI</doc> + <type name="Uri" c:type="GUri*"/> + </instance-parameter> + <parameter name="uri_ref" transfer-ownership="none"> + <doc xml:space="preserve">a string representing a relative or absolute URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to parse @uri_ref</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_uri_ref" version="2.66" introspectable="0"> + <doc xml:space="preserve">Increments the reference count of @uri by one.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">@uri</doc> + <type name="Uri" c:type="GUri*"/> + </return-value> + <parameters> + <instance-parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </instance-parameter> + </parameters> + </method> + <method name="to_string" c:identifier="g_uri_to_string" version="2.66"> + <doc xml:space="preserve">Returns a string representing @uri. + +This is not guaranteed to return a string which is identical to the +string that @uri was parsed from. However, if the source URI was +syntactically correct (according to RFC 3986), and it was parsed +with %G_URI_FLAGS_ENCODED, then g_uri_to_string() is guaranteed to return +a string which is at least semantically equivalent to the source +URI (according to RFC 3986). + +If @uri might contain sensitive details, such as authentication parameters, +or private data in its query string, and the returned string is going to be +logged, then consider using g_uri_to_string_partial() to redact parts.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a string representing @uri, + which the caller must free.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </instance-parameter> + </parameters> + </method> + <method name="to_string_partial" c:identifier="g_uri_to_string_partial" version="2.66"> + <doc xml:space="preserve">Returns a string representing @uri, subject to the options in +@flags. See g_uri_to_string() and #GUriHideFlags for more details.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a string representing + @uri, which the caller must free.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing what parts of @uri to hide</doc> + <type name="UriHideFlags" c:type="GUriHideFlags"/> + </parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_uri_unref" version="2.66" introspectable="0"> + <doc xml:space="preserve">Atomically decrements the reference count of @uri by one. + +When the reference count reaches zero, the resources allocated by +@uri are freed</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </instance-parameter> + </parameters> + </method> + <function name="build" c:identifier="g_uri_build" version="2.66"> + <doc xml:space="preserve">Creates a new #GUri from the given components according to @flags. + +See also g_uri_build_with_user(), which allows specifying the +components of the "userinfo" separately.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </return-value> + <parameters> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to build the #GUri</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + <parameter name="scheme" transfer-ownership="none"> + <doc xml:space="preserve">the URI scheme</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="userinfo" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the userinfo component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="host" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the host component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="port" transfer-ownership="none"> + <doc xml:space="preserve">the port, or `-1`</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the path component</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="query" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the query component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="fragment" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the fragment, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="build_with_user" c:identifier="g_uri_build_with_user" version="2.66"> + <doc xml:space="preserve">Creates a new #GUri from the given components according to @flags +(%G_URI_FLAGS_HAS_PASSWORD is added unconditionally). The @flags must be +coherent with the passed values, in particular use `%`-encoded values with +%G_URI_FLAGS_ENCODED. + +In contrast to g_uri_build(), this allows specifying the components +of the ‘userinfo’ field separately. Note that @user must be non-%NULL +if either @password or @auth_params is non-%NULL.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </return-value> + <parameters> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to build the #GUri</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + <parameter name="scheme" transfer-ownership="none"> + <doc xml:space="preserve">the URI scheme</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="user" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the user component of the userinfo, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="password" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the password component of the userinfo, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="auth_params" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the auth params of the userinfo, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="host" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the host component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="port" transfer-ownership="none"> + <doc xml:space="preserve">the port, or `-1`</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the path component</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="query" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the query component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="fragment" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the fragment, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="error_quark" c:identifier="g_uri_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="escape_bytes" c:identifier="g_uri_escape_bytes" version="2.66"> + <doc xml:space="preserve">Escapes arbitrary data 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. + +Though technically incorrect, this will also allow escaping nul +bytes as `%``00`.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an escaped version of @unescaped. + The returned string should be freed when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="unescaped" transfer-ownership="none"> + <doc xml:space="preserve">the unescaped input data.</doc> + <array length="1" zero-terminated="0" c:type="const guint8*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @unescaped</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="reserved_chars_allowed" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string of reserved + characters that are allowed to be used, or %NULL.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="escape_string" c:identifier="g_uri_escape_string" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an escaped version of @unescaped. The +returned string should be freed when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="unescaped" transfer-ownership="none"> + <doc xml:space="preserve">the unescaped input string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="reserved_chars_allowed" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string of reserved + characters that are allowed to be used, or %NULL.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="allow_utf8" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the result can include UTF-8 characters.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="is_valid" c:identifier="g_uri_is_valid" version="2.66" throws="1"> + <doc xml:space="preserve">Parses @uri_string according to @flags, to determine whether it is a valid +[absolute URI][relative-absolute-uris], i.e. it does not need to be resolved +relative to another URI using g_uri_parse_relative(). + +If it’s not a valid URI, an error is returned explaining how it’s invalid. + +See g_uri_split(), and the definition of #GUriFlags, for more +information on the effect of @flags.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @uri_string is a valid absolute URI, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="uri_string" transfer-ownership="none"> + <doc xml:space="preserve">a string containing an absolute URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for parsing @uri_string</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + </parameters> + </function> + <function name="join" c:identifier="g_uri_join" version="2.66"> + <doc xml:space="preserve">Joins the given components together according to @flags to create +an absolute URI string. @path may not be %NULL (though it may be the empty +string). + +When @host is present, @path must either be empty or begin with a slash (`/`) +character. When @host is not present, @path cannot begin with two slash + characters (`//`). See +[RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3). + +See also g_uri_join_with_user(), which allows specifying the +components of the ‘userinfo’ separately. + +%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set +in @flags.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an absolute URI string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to build the URI string</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + <parameter name="scheme" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the URI scheme, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="userinfo" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the userinfo component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="host" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the host component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="port" transfer-ownership="none"> + <doc xml:space="preserve">the port, or `-1`</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the path component</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="query" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the query component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="fragment" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the fragment, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="join_with_user" c:identifier="g_uri_join_with_user" version="2.66"> + <doc xml:space="preserve">Joins the given components together according to @flags to create +an absolute URI string. @path may not be %NULL (though it may be the empty +string). + +In contrast to g_uri_join(), this allows specifying the components +of the ‘userinfo’ separately. It otherwise behaves the same. + +%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set +in @flags.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an absolute URI string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to build the URI string</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + <parameter name="scheme" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the URI scheme, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="user" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the user component of the userinfo, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="password" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the password component of the userinfo, or + %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="auth_params" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the auth params of the userinfo, or + %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="host" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the host component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="port" transfer-ownership="none"> + <doc xml:space="preserve">the port, or `-1`</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the path component</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="query" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the query component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="fragment" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the fragment, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="list_extract_uris" c:identifier="g_uri_list_extract_uris" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated %NULL-terminated list + of strings holding the individual URIs. The array should be freed + with g_strfreev().</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="uri_list" transfer-ownership="none"> + <doc xml:space="preserve">an URI list</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="parse" c:identifier="g_uri_parse" version="2.66" throws="1"> + <doc xml:space="preserve">Parses @uri_string according to @flags. If the result is not a +valid [absolute URI][relative-absolute-uris], it will be discarded, and an +error returned.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUri, or NULL on error.</doc> + <type name="Uri" c:type="GUri*"/> + </return-value> + <parameters> + <parameter name="uri_string" transfer-ownership="none"> + <doc xml:space="preserve">a string representing an absolute URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to parse @uri_string</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + </parameters> + </function> + <function name="parse_params" c:identifier="g_uri_parse_params" version="2.66" throws="1"> + <doc xml:space="preserve">Many URI schemes include one or more attribute/value pairs as part of the URI +value. This method can be used to parse them into a hash table. When an +attribute has multiple occurrences, the last value is the final returned +value. If you need to handle repeated attributes differently, use +#GUriParamsIter. + +The @params string is assumed to still be `%`-encoded, but the returned +values will be fully decoded. (Thus it is possible that the returned values +may contain `=` or @separators, if the value was encoded in the input.) +Invalid `%`-encoding is treated as with the %G_URI_FLAGS_PARSE_RELAXED +rules for g_uri_parse(). (However, if @params is the path or query string +from a #GUri that was parsed without %G_URI_FLAGS_PARSE_RELAXED and +%G_URI_FLAGS_ENCODED, then you already know that it does not contain any +invalid encoding.) + +%G_URI_PARAMS_WWW_FORM is handled as documented for g_uri_params_iter_init(). + +If %G_URI_PARAMS_CASE_INSENSITIVE is passed to @flags, attributes will be +compared case-insensitively, so a params string `attr=123&Attr=456` will only +return a single attribute–value pair, `Attr=456`. Case will be preserved in +the returned attributes. + +If @params cannot be parsed (for example, it contains two @separators +characters in a row), then @error is set and %NULL is returned.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + A hash table of attribute/value pairs, with both names and values + fully-decoded; or %NULL on error.</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="utf8"/> + <type name="utf8"/> + </type> + </return-value> + <parameters> + <parameter name="params" transfer-ownership="none"> + <doc xml:space="preserve">a `%`-encoded string containing `attribute=value` + parameters</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @params, or `-1` if it is nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="separators" transfer-ownership="none"> + <doc xml:space="preserve">the separator byte character set between parameters. (usually + `&`, but sometimes `;` or both `&;`). 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. You may pass an empty set, in which case + no splitting will occur.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags to modify the way the parameters are handled.</doc> + <type name="UriParamsFlags" c:type="GUriParamsFlags"/> + </parameter> + </parameters> + </function> + <function name="parse_scheme" c:identifier="g_uri_parse_scheme" version="2.16"> + <doc xml:space="preserve">Gets the scheme portion of a URI string. +[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme +as: +|[ +URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] +]| +Common schemes include `file`, `https`, `svn+ssh`, etc.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">The ‘scheme’ component of the URI, or + %NULL on error. The returned string should be freed when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="peek_scheme" c:identifier="g_uri_peek_scheme" version="2.66"> + <doc xml:space="preserve">Gets the scheme portion of a URI string. +[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme +as: +|[ +URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] +]| +Common schemes include `file`, `https`, `svn+ssh`, etc. + +Unlike g_uri_parse_scheme(), the returned scheme is normalized to +all-lowercase and does not need to be freed.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The ‘scheme’ component of the URI, or + %NULL on error. The returned string is normalized to all-lowercase, and + interned via g_intern_string(), so it does not need to be freed.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="resolve_relative" c:identifier="g_uri_resolve_relative" version="2.66" throws="1"> + <doc xml:space="preserve">Parses @uri_ref according to @flags and, if it is a +[relative URI][relative-absolute-uris], resolves it relative to +@base_uri_string. If the result is not a valid absolute URI, it will be +discarded, and an error returned. + +(If @base_uri_string is %NULL, this just returns @uri_ref, or +%NULL if @uri_ref is invalid or not absolute.)</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the resolved URI string, +or NULL on error.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="base_uri_string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string representing a base URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="uri_ref" transfer-ownership="none"> + <doc xml:space="preserve">a string representing a relative or absolute URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to parse @uri_ref</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + </parameters> + </function> + <function name="split" c:identifier="g_uri_split" version="2.66" throws="1"> + <doc xml:space="preserve">Parses @uri_ref (which can be an +[absolute or relative URI][relative-absolute-uris]) according to @flags, and +returns the pieces. Any component that doesn't appear in @uri_ref will be +returned as %NULL (but note that all URIs always have a path component, +though it may be the empty string). + +If @flags contains %G_URI_FLAGS_ENCODED, then `%`-encoded characters in +@uri_ref will remain encoded in the output strings. (If not, +then all such characters will be decoded.) Note that decoding will +only work if the URI components are ASCII or UTF-8, so you will +need to use %G_URI_FLAGS_ENCODED if they are not. + +Note that the %G_URI_FLAGS_HAS_PASSWORD and +%G_URI_FLAGS_HAS_AUTH_PARAMS @flags are ignored by g_uri_split(), +since it always returns only the full userinfo; use +g_uri_split_with_user() if you want it split up.</doc> + <return-value transfer-ownership="none" skip="1"> + <doc xml:space="preserve">%TRUE if @uri_ref parsed successfully, %FALSE + on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="uri_ref" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a relative or absolute URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for parsing @uri_ref</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + <parameter name="scheme" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the scheme (converted to lowercase), or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="userinfo" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the userinfo, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="host" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + host, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="port" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + port, or `-1`</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="path" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + path</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="query" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + query, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="fragment" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the fragment, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </function> + <function name="split_network" c:identifier="g_uri_split_network" version="2.66" throws="1"> + <doc xml:space="preserve">Parses @uri_string (which must be an [absolute URI][relative-absolute-uris]) +according to @flags, and returns the pieces relevant to connecting to a host. +See the documentation for g_uri_split() for more details; this is +mostly a wrapper around that function with simpler arguments. +However, it will return an error if @uri_string is a relative URI, +or does not contain a hostname component.</doc> + <return-value transfer-ownership="none" skip="1"> + <doc xml:space="preserve">%TRUE if @uri_string parsed successfully, + %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="uri_string" transfer-ownership="none"> + <doc xml:space="preserve">a string containing an absolute URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for parsing @uri_string</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + <parameter name="scheme" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the scheme (converted to lowercase), or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="host" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + host, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="port" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + port, or `-1`</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </function> + <function name="split_with_user" c:identifier="g_uri_split_with_user" version="2.66" throws="1"> + <doc xml:space="preserve">Parses @uri_ref (which can be an +[absolute or relative URI][relative-absolute-uris]) according to @flags, and +returns the pieces. Any component that doesn't appear in @uri_ref will be +returned as %NULL (but note that all URIs always have a path component, +though it may be the empty string). + +See g_uri_split(), and the definition of #GUriFlags, for more +information on the effect of @flags. Note that @password will only +be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and +@auth_params will only be parsed out if @flags contains +%G_URI_FLAGS_HAS_AUTH_PARAMS.</doc> + <return-value transfer-ownership="none" skip="1"> + <doc xml:space="preserve">%TRUE if @uri_ref parsed successfully, %FALSE + on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="uri_ref" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a relative or absolute URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for parsing @uri_ref</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + <parameter name="scheme" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the scheme (converted to lowercase), or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="user" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the user, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="password" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the password, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="auth_params" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the auth_params, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="host" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + host, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="port" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + port, or `-1`</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="path" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + path</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="query" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + query, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="fragment" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the fragment, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </function> + <function name="unescape_bytes" c:identifier="g_uri_unescape_bytes" version="2.66" throws="1"> + <doc xml:space="preserve">Unescapes a segment of an escaped string as binary data. + +Note that in contrast to g_uri_unescape_string(), this does allow +nul bytes to appear in the output. + +If any of the characters in @illegal_characters appears as an escaped +character in @escaped_string, then that is an error and %NULL will be +returned. This is useful if you want to avoid for instance having a slash +being expanded in an escaped path element, which might confuse pathname +handling.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an unescaped version of @escaped_string + or %NULL on error (if decoding failed, using %G_URI_ERROR_FAILED error + code). The returned #GBytes should be unreffed when no longer needed.</doc> + <type name="Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <parameter name="escaped_string" transfer-ownership="none"> + <doc xml:space="preserve">A URI-escaped string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length (in bytes) of @escaped_string to escape, or `-1` if it + is nul-terminated.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="illegal_characters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string of illegal characters + not to be allowed, or %NULL.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="unescape_segment" c:identifier="g_uri_unescape_segment" version="2.16"> + <doc xml:space="preserve">Unescapes a segment of an escaped string. + +If any of the characters in @illegal_characters or the NUL +character appears as an escaped character in @escaped_string, then +that is an error and %NULL will be returned. This is useful if you +want to avoid for instance having a slash being expanded in an +escaped path element, which might confuse pathname handling. + +Note: `NUL` byte is not accepted in the output, in contrast to +g_uri_unescape_bytes().</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="escaped_string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A string, may be %NULL</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="escaped_string_end" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Pointer to end of @escaped_string, + may be %NULL</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="illegal_characters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">An optional string of illegal + characters not to be allowed, may be %NULL</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="unescape_string" c:identifier="g_uri_unescape_string" version="2.16"> + <doc xml:space="preserve">Unescapes a whole escaped string. + +If any of the characters in @illegal_characters or the NUL +character appears as an escaped character in @escaped_string, then +that is an error and %NULL will be returned. This is useful if you +want to avoid for instance having a slash being expanded in an +escaped path element, which might confuse pathname handling.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">an unescaped version of @escaped_string. +The returned string should be freed when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="escaped_string" transfer-ownership="none"> + <doc xml:space="preserve">an escaped string to be unescaped.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="illegal_characters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string of illegal characters + not to be allowed, or %NULL.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + </record> + <enumeration name="UriError" version="2.66" c:type="GUriError" glib:error-domain="g-uri-quark"> + <doc xml:space="preserve">Error codes returned by #GUri methods.</doc> + <member name="failed" value="0" c:identifier="G_URI_ERROR_FAILED"> + <doc xml:space="preserve">Generic error if no more specific error is available. + See the error message for details.</doc> + </member> + <member name="bad_scheme" value="1" c:identifier="G_URI_ERROR_BAD_SCHEME"> + <doc xml:space="preserve">The scheme of a URI could not be parsed.</doc> + </member> + <member name="bad_user" value="2" c:identifier="G_URI_ERROR_BAD_USER"> + <doc xml:space="preserve">The user/userinfo of a URI could not be parsed.</doc> + </member> + <member name="bad_password" value="3" c:identifier="G_URI_ERROR_BAD_PASSWORD"> + <doc xml:space="preserve">The password of a URI could not be parsed.</doc> + </member> + <member name="bad_auth_params" value="4" c:identifier="G_URI_ERROR_BAD_AUTH_PARAMS"> + <doc xml:space="preserve">The authentication parameters of a URI could not be parsed.</doc> + </member> + <member name="bad_host" value="5" c:identifier="G_URI_ERROR_BAD_HOST"> + <doc xml:space="preserve">The host of a URI could not be parsed.</doc> + </member> + <member name="bad_port" value="6" c:identifier="G_URI_ERROR_BAD_PORT"> + <doc xml:space="preserve">The port of a URI could not be parsed.</doc> + </member> + <member name="bad_path" value="7" c:identifier="G_URI_ERROR_BAD_PATH"> + <doc xml:space="preserve">The path of a URI could not be parsed.</doc> + </member> + <member name="bad_query" value="8" c:identifier="G_URI_ERROR_BAD_QUERY"> + <doc xml:space="preserve">The query of a URI could not be parsed.</doc> + </member> + <member name="bad_fragment" value="9" c:identifier="G_URI_ERROR_BAD_FRAGMENT"> + <doc xml:space="preserve">The fragment of a URI could not be parsed.</doc> + </member> + </enumeration> + <bitfield name="UriFlags" version="2.66" c:type="GUriFlags"> + <doc xml:space="preserve">Flags that describe a URI. + +When parsing a URI, if you need to choose different flags based on +the type of URI, you can use g_uri_peek_scheme() on the URI string +to check the scheme first, and use that to decide what flags to +parse it with.</doc> + <member name="none" value="0" c:identifier="G_URI_FLAGS_NONE"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="parse_relaxed" value="1" c:identifier="G_URI_FLAGS_PARSE_RELAXED"> + <doc xml:space="preserve">Parse the URI more relaxedly than the + [RFC 3986](https://tools.ietf.org/html/rfc3986) grammar specifies, + fixing up or ignoring common mistakes in URIs coming from external + sources. This is also needed for some obscure URI schemes where `;` + separates the host from the path. Don’t use this flag unless you need to.</doc> + </member> + <member name="has_password" value="2" c:identifier="G_URI_FLAGS_HAS_PASSWORD"> + <doc xml:space="preserve">The userinfo field may contain a password, + which will be separated from the username by `:`.</doc> + </member> + <member name="has_auth_params" value="4" c:identifier="G_URI_FLAGS_HAS_AUTH_PARAMS"> + <doc xml:space="preserve">The userinfo may contain additional + authentication-related parameters, which will be separated from + the username and/or password by `;`.</doc> + </member> + <member name="encoded" value="8" c:identifier="G_URI_FLAGS_ENCODED"> + <doc xml:space="preserve">When parsing a URI, this indicates that `%`-encoded + characters in the userinfo, path, query, and fragment fields + should not be decoded. (And likewise the host field if + %G_URI_FLAGS_NON_DNS is also set.) When building a URI, it indicates + that you have already `%`-encoded the components, and so #GUri + should not do any encoding itself.</doc> + </member> + <member name="non_dns" value="16" c:identifier="G_URI_FLAGS_NON_DNS"> + <doc xml:space="preserve">The host component should not be assumed to be a + DNS hostname or IP address (for example, for `smb` URIs with NetBIOS + hostnames).</doc> + </member> + <member name="encoded_query" value="32" c:identifier="G_URI_FLAGS_ENCODED_QUERY"> + <doc xml:space="preserve">Same as %G_URI_FLAGS_ENCODED, for the query + field only.</doc> + </member> + <member name="encoded_path" value="64" c:identifier="G_URI_FLAGS_ENCODED_PATH"> + <doc xml:space="preserve">Same as %G_URI_FLAGS_ENCODED, for the path only.</doc> + </member> + <member name="encoded_fragment" value="128" c:identifier="G_URI_FLAGS_ENCODED_FRAGMENT"> + <doc xml:space="preserve">Same as %G_URI_FLAGS_ENCODED, for the + fragment only.</doc> + </member> + </bitfield> + <bitfield name="UriHideFlags" version="2.66" c:type="GUriHideFlags"> + <doc xml:space="preserve">Flags describing what parts of the URI to hide in +g_uri_to_string_partial(). Note that %G_URI_HIDE_PASSWORD and +%G_URI_HIDE_AUTH_PARAMS will only work if the #GUri was parsed with +the corresponding flags.</doc> + <member name="none" value="0" c:identifier="G_URI_HIDE_NONE"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="userinfo" value="1" c:identifier="G_URI_HIDE_USERINFO"> + <doc xml:space="preserve">Hide the userinfo.</doc> + </member> + <member name="password" value="2" c:identifier="G_URI_HIDE_PASSWORD"> + <doc xml:space="preserve">Hide the password.</doc> + </member> + <member name="auth_params" value="4" c:identifier="G_URI_HIDE_AUTH_PARAMS"> + <doc xml:space="preserve">Hide the auth_params.</doc> + </member> + <member name="query" value="8" c:identifier="G_URI_HIDE_QUERY"> + <doc xml:space="preserve">Hide the query.</doc> + </member> + <member name="fragment" value="16" c:identifier="G_URI_HIDE_FRAGMENT"> + <doc xml:space="preserve">Hide the fragment.</doc> + </member> + </bitfield> + <bitfield name="UriParamsFlags" version="2.66" c:type="GUriParamsFlags"> + <doc xml:space="preserve">Flags modifying the way parameters are handled by g_uri_parse_params() and +#GUriParamsIter.</doc> + <member name="none" value="0" c:identifier="G_URI_PARAMS_NONE"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="case_insensitive" value="1" c:identifier="G_URI_PARAMS_CASE_INSENSITIVE"> + <doc xml:space="preserve">Parameter names are case insensitive.</doc> + </member> + <member name="www_form" value="2" c:identifier="G_URI_PARAMS_WWW_FORM"> + <doc xml:space="preserve">Replace `+` with space character. Only useful for + URLs on the web, using the `https` or `http` schemas.</doc> + </member> + <member name="parse_relaxed" value="4" c:identifier="G_URI_PARAMS_PARSE_RELAXED"> + <doc xml:space="preserve">See %G_URI_FLAGS_PARSE_RELAXED.</doc> + </member> + </bitfield> + <record name="UriParamsIter" c:type="GUriParamsIter" version="2.66"> + <doc xml:space="preserve">Many URI schemes include one or more attribute/value pairs as part of the URI +value. For example `scheme://server/path?query=string&is=there` has two +attributes – `query=string` and `is=there` – in its query part. + +A #GUriParamsIter structure represents an iterator that can be used to +iterate over the attribute/value pairs of a URI query string. #GUriParamsIter +structures are typically allocated on the stack and then initialized with +g_uri_params_iter_init(). See the documentation for g_uri_params_iter_init() +for a usage example.</doc> + <field name="dummy0" readable="0" private="1"> + <type name="gint" c:type="gint"/> + </field> + <field name="dummy1" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="dummy2" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="dummy3" readable="0" private="1"> + <array zero-terminated="0" fixed-size="256"> + <type name="guint8" c:type="guint8"/> + </array> + </field> + <method name="init" c:identifier="g_uri_params_iter_init" version="2.66"> + <doc xml:space="preserve">Initializes an attribute/value pair iterator. + +The iterator keeps pointers to the @params and @separators arguments, those +variables must thus outlive the iterator and not be modified during the +iteration. + +If %G_URI_PARAMS_WWW_FORM is passed in @flags, `+` characters in the param +string will be replaced with spaces in the output. For example, `foo=bar+baz` +will give attribute `foo` with value `bar baz`. This is commonly used on the +web (the `https` and `http` schemes only), but is deprecated in favour of +the equivalent of encoding spaces as `%20`. + +Unlike with g_uri_parse_params(), %G_URI_PARAMS_CASE_INSENSITIVE has no +effect if passed to @flags for g_uri_params_iter_init(). The caller is +responsible for doing their own case-insensitive comparisons. + +|[<!-- language="C" --> +GUriParamsIter iter; +GError *error = NULL; +gchar *unowned_attr, *unowned_value; + +g_uri_params_iter_init (&iter, "foo=bar&baz=bar&Foo=frob&baz=bar2", -1, "&", G_URI_PARAMS_NONE); +while (g_uri_params_iter_next (&iter, &unowned_attr, &unowned_value, &error)) + { + g_autofree gchar *attr = g_steal_pointer (&unowned_attr); + g_autofree gchar *value = g_steal_pointer (&unowned_value); + // do something with attr and value; this code will be called 4 times + // for the params string in this example: once with attr=foo and value=bar, + // then with baz/bar, then Foo/frob, then baz/bar2. + } +if (error) + // handle parsing error +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">an uninitialized #GUriParamsIter</doc> + <type name="UriParamsIter" c:type="GUriParamsIter*"/> + </instance-parameter> + <parameter name="params" transfer-ownership="none"> + <doc xml:space="preserve">a `%`-encoded string containing `attribute=value` + parameters</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @params, or `-1` if it is nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="separators" transfer-ownership="none"> + <doc xml:space="preserve">the separator byte character set between parameters. (usually + `&`, but sometimes `;` or both `&;`). 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. You may pass an empty set, in which case + no splitting will occur.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags to modify the way the parameters are handled.</doc> + <type name="UriParamsFlags" c:type="GUriParamsFlags"/> + </parameter> + </parameters> + </method> + <method name="next" c:identifier="g_uri_params_iter_next" version="2.66" throws="1"> + <doc xml:space="preserve">Advances @iter and retrieves the next attribute/value. %FALSE is returned if +an error has occurred (in which case @error is set), or if the end of the +iteration is reached (in which case @attribute and @value are set to %NULL +and the iterator becomes invalid). If %TRUE is returned, +g_uri_params_iter_next() may be called again to receive another +attribute/value pair. + +Note that the same @attribute may be returned multiple times, since URIs +allow repeated attributes.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%FALSE if the end of the parameters has been reached or an error was + encountered. %TRUE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">an initialized #GUriParamsIter</doc> + <type name="UriParamsIter" c:type="GUriParamsIter*"/> + </instance-parameter> + <parameter name="attribute" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the attribute, or %NULL.</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the value, or %NULL.</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </method> + </record> + <enumeration name="UserDirectory" version="2.14" c:type="GUserDirectory"> + <doc xml:space="preserve">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.</doc> + <member name="directory_desktop" value="0" c:identifier="G_USER_DIRECTORY_DESKTOP"> + <doc xml:space="preserve">the user's Desktop directory</doc> + </member> + <member name="directory_documents" value="1" c:identifier="G_USER_DIRECTORY_DOCUMENTS"> + <doc xml:space="preserve">the user's Documents directory</doc> + </member> + <member name="directory_download" value="2" c:identifier="G_USER_DIRECTORY_DOWNLOAD"> + <doc xml:space="preserve">the user's Downloads directory</doc> + </member> + <member name="directory_music" value="3" c:identifier="G_USER_DIRECTORY_MUSIC"> + <doc xml:space="preserve">the user's Music directory</doc> + </member> + <member name="directory_pictures" value="4" c:identifier="G_USER_DIRECTORY_PICTURES"> + <doc xml:space="preserve">the user's Pictures directory</doc> + </member> + <member name="directory_public_share" value="5" c:identifier="G_USER_DIRECTORY_PUBLIC_SHARE"> + <doc xml:space="preserve">the user's shared directory</doc> + </member> + <member name="directory_templates" value="6" c:identifier="G_USER_DIRECTORY_TEMPLATES"> + <doc xml:space="preserve">the user's Templates directory</doc> + </member> + <member name="directory_videos" value="7" c:identifier="G_USER_DIRECTORY_VIDEOS"> + <doc xml:space="preserve">the user's Movies directory</doc> + </member> + <member name="n_directories" value="8" c:identifier="G_USER_N_DIRECTORIES"> + <doc xml:space="preserve">the number of enum values</doc> + </member> + </enumeration> + <function-macro name="VARIANT_BUILDER_INIT" c:identifier="G_VARIANT_BUILDER_INIT" version="2.50" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <parameters> + <parameter name="variant_type"> + <doc xml:space="preserve">a const GVariantType*</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VARIANT_DICT_INIT" c:identifier="G_VARIANT_DICT_INIT" version="2.50" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <parameters> + <parameter name="asv"> + <doc xml:space="preserve">a GVariant*</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VARIANT_TYPE" c:identifier="G_VARIANT_TYPE" introspectable="0"> + <doc xml:space="preserve">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</doc> + <parameters> + <parameter name="type_string"> + <doc xml:space="preserve">a well-formed #GVariantType type string</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VA_COPY" c:identifier="G_VA_COPY" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="ap1"> + <doc xml:space="preserve">the va_list variable to place a copy of @ap2 in</doc> + </parameter> + <parameter name="ap2"> + <doc xml:space="preserve">a va_list</doc> + </parameter> + </parameters> + </function-macro> + <constant name="VA_COPY_AS_ARRAY" value="1" c:type="G_VA_COPY_AS_ARRAY"> + <type name="gint" c:type="gint"/> + </constant> + <constant name="VERSION_MIN_REQUIRED" value="2" c:type="GLIB_VERSION_MIN_REQUIRED" version="2.32"> + <doc xml:space="preserve">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).</doc> + <type name="gint" c:type="gint"/> + </constant> + <record name="Variant" c:type="GVariant" version="2.24" glib:type-name="GVariant" glib:get-type="intern" c:symbol-prefix="variant"> + <doc xml:space="preserve">#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 D-Bus, 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.</doc> + <constructor name="new" c:identifier="g_variant_new" version="2.24" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new floating #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="format_string" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">arguments, as per @format_string</doc> + <varargs/> + </parameter> + </parameters> + </constructor> + <constructor name="new_array" c:identifier="g_variant_new_array" version="2.24"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new #GVariant array</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="child_type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the element type of the new array</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="children" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an array of + #GVariant pointers, the children</doc> + <array length="2" zero-terminated="0" c:type="GVariant* const*"> + <type name="Variant" c:type="GVariant*"/> + </array> + </parameter> + <parameter name="n_children" transfer-ownership="none"> + <doc xml:space="preserve">the length of @children</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_boolean" c:identifier="g_variant_new_boolean" version="2.24"> + <doc xml:space="preserve">Creates a new boolean #GVariant instance -- either %TRUE or %FALSE.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new boolean #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #gboolean value</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_byte" c:identifier="g_variant_new_byte" version="2.24"> + <doc xml:space="preserve">Creates a new byte #GVariant instance.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new byte #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #guint8 value</doc> + <type name="guint8" c:type="guint8"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_bytestring" c:identifier="g_variant_new_bytestring" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new bytestring #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a normal + nul-terminated string in no particular encoding</doc> + <array c:type="const gchar*"> + <type name="guint8"/> + </array> + </parameter> + </parameters> + </constructor> + <constructor name="new_bytestring_array" c:identifier="g_variant_new_bytestring_array" version="2.26"> + <doc xml:space="preserve">Constructs an array of bytestring #GVariant from the given array of +strings. + +If @length is -1 then @strv is %NULL-terminated.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a new floating #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="strv" transfer-ownership="none"> + <doc xml:space="preserve">an array of strings</doc> + <array length="1" zero-terminated="0" c:type="const gchar* const*"> + <type name="utf8" c:type="gchar*"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @strv, or -1</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_dict_entry" c:identifier="g_variant_new_dict_entry" version="2.24"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new dictionary entry #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a basic #GVariant, the key</doc> + <type name="Variant" c:type="GVariant*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant, the value</doc> + <type name="Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_double" c:identifier="g_variant_new_double" version="2.24"> + <doc xml:space="preserve">Creates a new double #GVariant instance.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new double #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #gdouble floating point value</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_fixed_array" c:identifier="g_variant_new_fixed_array" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new array #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="element_type" transfer-ownership="none"> + <doc xml:space="preserve">the #GVariantType of each element</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="elements" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to the fixed array of contiguous elements</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="n_elements" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="element_size" transfer-ownership="none"> + <doc xml:space="preserve">the size of each element</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_bytes" c:identifier="g_variant_new_from_bytes" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a new #GVariant with a floating reference</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="bytes" transfer-ownership="none"> + <doc xml:space="preserve">a #GBytes</doc> + <type name="Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="trusted" transfer-ownership="none"> + <doc xml:space="preserve">if the contents of @bytes are trusted</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_data" c:identifier="g_variant_new_from_data" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a new floating #GVariant of type @type</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a definite #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">the serialised data</doc> + <array length="2" zero-terminated="0" c:type="gconstpointer"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">the size of @data</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="trusted" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @data is definitely in normal form</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="notify" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">function to call when @data is no longer needed</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data for @notify</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_handle" c:identifier="g_variant_new_handle" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new handle #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #gint32 value</doc> + <type name="gint32" c:type="gint32"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_int16" c:identifier="g_variant_new_int16" version="2.24"> + <doc xml:space="preserve">Creates a new int16 #GVariant instance.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new int16 #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #gint16 value</doc> + <type name="gint16" c:type="gint16"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_int32" c:identifier="g_variant_new_int32" version="2.24"> + <doc xml:space="preserve">Creates a new int32 #GVariant instance.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new int32 #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #gint32 value</doc> + <type name="gint32" c:type="gint32"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_int64" c:identifier="g_variant_new_int64" version="2.24"> + <doc xml:space="preserve">Creates a new int64 #GVariant instance.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new int64 #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #gint64 value</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_maybe" c:identifier="g_variant_new_maybe" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new #GVariant maybe instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="child_type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the #GVariantType of the child, or %NULL</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="child" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the child value, or %NULL</doc> + <type name="Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_object_path" c:identifier="g_variant_new_object_path" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new object path #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">a normal C nul-terminated string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_objv" c:identifier="g_variant_new_objv" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a new floating #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="strv" transfer-ownership="none"> + <doc xml:space="preserve">an array of strings</doc> + <array length="1" zero-terminated="0" c:type="const gchar* const*"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @strv, or -1</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_parsed" c:identifier="g_variant_new_parsed" introspectable="0"> + <doc xml:space="preserve">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 "%@".</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new floating #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a text format #GVariant</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">arguments as per @format</doc> + <varargs/> + </parameter> + </parameters> + </constructor> + <constructor name="new_parsed_va" c:identifier="g_variant_new_parsed_va" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new, usually floating, #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a text format #GVariant</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="app" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #va_list</doc> + <type name="va_list" c:type="va_list*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_printf" c:identifier="g_variant_new_printf" version="2.38" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new string + #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="format_string" transfer-ownership="none"> + <doc xml:space="preserve">a printf-style format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">arguments for @format_string</doc> + <varargs/> + </parameter> + </parameters> + </constructor> + <constructor name="new_signature" c:identifier="g_variant_new_signature" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new signature #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="signature" transfer-ownership="none"> + <doc xml:space="preserve">a normal C nul-terminated string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_string" c:identifier="g_variant_new_string" version="2.24"> + <doc xml:space="preserve">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].</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new string #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a normal UTF-8 nul-terminated string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_strv" c:identifier="g_variant_new_strv" version="2.24"> + <doc xml:space="preserve">Constructs an array of strings #GVariant from the given array of +strings. + +If @length is -1 then @strv is %NULL-terminated.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a new floating #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="strv" transfer-ownership="none"> + <doc xml:space="preserve">an array of strings</doc> + <array length="1" zero-terminated="0" c:type="const gchar* const*"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @strv, or -1</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_take_string" c:identifier="g_variant_new_take_string" version="2.38" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new string + #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a normal UTF-8 nul-terminated string</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_tuple" c:identifier="g_variant_new_tuple" version="2.24"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new #GVariant tuple</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="children" transfer-ownership="none"> + <doc xml:space="preserve">the items to make the tuple out of</doc> + <array length="1" zero-terminated="0" c:type="GVariant* const*"> + <type name="Variant" c:type="GVariant*"/> + </array> + </parameter> + <parameter name="n_children" transfer-ownership="none"> + <doc xml:space="preserve">the length of @children</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_uint16" c:identifier="g_variant_new_uint16" version="2.24"> + <doc xml:space="preserve">Creates a new uint16 #GVariant instance.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new uint16 #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #guint16 value</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_uint32" c:identifier="g_variant_new_uint32" version="2.24"> + <doc xml:space="preserve">Creates a new uint32 #GVariant instance.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new uint32 #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #guint32 value</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_uint64" c:identifier="g_variant_new_uint64" version="2.24"> + <doc xml:space="preserve">Creates a new uint64 #GVariant instance.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new uint64 #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #guint64 value</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_va" c:identifier="g_variant_new_va" version="2.24" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new, usually floating, #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="format_string" transfer-ownership="none"> + <doc xml:space="preserve">a string that is prefixed with a format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="endptr" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">location to store the end pointer, + or %NULL</doc> + <type name="utf8" c:type="const gchar**"/> + </parameter> + <parameter name="app" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #va_list</doc> + <type name="va_list" c:type="va_list*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_variant" c:identifier="g_variant_new_variant" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new variant #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </constructor> + <method name="byteswap" c:identifier="g_variant_byteswap" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the byteswapped form of @value</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="check_format_string" c:identifier="g_variant_check_format_string" version="2.34"> + <doc xml:space="preserve">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()).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @format_string is safe to use</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="format_string" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GVariant format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="copy_only" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to ensure the format string makes deep copies</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="classify" c:identifier="g_variant_classify" version="2.24"> + <doc xml:space="preserve">Classifies @value according to its top-level type.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GVariantClass of @value</doc> + <type name="VariantClass" c:type="GVariantClass"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="compare" c:identifier="g_variant_compare" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">negative value if a < b; + zero if a = b; + positive value if a > b.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="one" transfer-ownership="none"> + <doc xml:space="preserve">a basic-typed #GVariant instance</doc> + <type name="Variant" c:type="gconstpointer"/> + </instance-parameter> + <parameter name="two" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant instance of the same type</doc> + <type name="Variant" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="dup_bytestring" c:identifier="g_variant_dup_bytestring" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + a newly allocated string</doc> + <array length="0" zero-terminated="1" c:type="gchar*"> + <type name="guint8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">an array-of-bytes #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a pointer to a #gsize, to store + the length (not including the nul terminator)</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="dup_bytestring_array" c:identifier="g_variant_dup_bytestring_array" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an array of strings</doc> + <array length="0" zero-terminated="0" c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">an array of array of bytes #GVariant ('aay')</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the length of the result, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="dup_objv" c:identifier="g_variant_dup_objv" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an array of strings</doc> + <array length="0" zero-terminated="1" c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">an array of object paths #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the length of the result, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="dup_string" c:identifier="g_variant_dup_string" version="2.24"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string, UTF-8 encoded</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a string #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">a pointer to a #gsize, to store the length</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="dup_strv" c:identifier="g_variant_dup_strv" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an array of strings</doc> + <array length="0" zero-terminated="1" c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">an array of strings #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the length of the result, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="equal" c:identifier="g_variant_equal" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @one and @two are equal</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="one" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant instance</doc> + <type name="Variant" c:type="gconstpointer"/> + </instance-parameter> + <parameter name="two" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant instance</doc> + <type name="Variant" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="get" c:identifier="g_variant_get" version="2.24" introspectable="0"> + <doc xml:space="preserve">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].</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="format_string" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">arguments, as per @format_string</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="get_boolean" c:identifier="g_variant_get_boolean" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE or %FALSE</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a boolean #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_byte" c:identifier="g_variant_get_byte" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #guint8</doc> + <type name="guint8" c:type="guint8"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a byte #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_bytestring" c:identifier="g_variant_get_bytestring" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve"> + the constant string</doc> + <array c:type="const gchar*"> + <type name="guint8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">an array-of-bytes #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_bytestring_array" c:identifier="g_variant_get_bytestring_array" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="container"> + <doc xml:space="preserve">an array of constant strings</doc> + <array length="0" zero-terminated="0" c:type="const gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">an array of array of bytes #GVariant ('aay')</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the length of the result, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_child" c:identifier="g_variant_get_child" version="2.24" introspectable="0"> + <doc xml:space="preserve">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].</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a container #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">the index of the child to deconstruct</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="format_string" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">arguments, as per @format_string</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="get_child_value" c:identifier="g_variant_get_child_value" version="2.24"> + <doc xml:space="preserve">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. + +Note that values borrowed from the returned child are not guaranteed to +still be valid after the child is freed even if you still hold a reference +to @value, if @value has not been serialised at the time this function is +called. To avoid this, you can serialize @value by calling +g_variant_get_data() and optionally ignoring the return value. + +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).</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the child at the specified index</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a container #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">the index of the child to fetch</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <method name="get_data" c:identifier="g_variant_get_data" version="2.24"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the serialised form of @value, or %NULL</doc> + <type name="gpointer" c:type="gconstpointer"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_data_as_bytes" c:identifier="g_variant_get_data_as_bytes" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A new #GBytes representing the variant data</doc> + <type name="Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_double" c:identifier="g_variant_get_double" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #gdouble</doc> + <type name="gdouble" c:type="gdouble"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a double #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_fixed_array" c:identifier="g_variant_get_fixed_array" version="2.24" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a pointer to + the fixed array</doc> + <array length="0" zero-terminated="0" c:type="gconstpointer"> + <type name="gpointer" c:type="gconstpointer"/> + </array> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant array with fixed-sized elements</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="n_elements" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">a pointer to the location to store the number of items</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="element_size" transfer-ownership="none"> + <doc xml:space="preserve">the size of each element</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <method name="get_handle" c:identifier="g_variant_get_handle" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #gint32</doc> + <type name="gint32" c:type="gint32"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a handle #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_int16" c:identifier="g_variant_get_int16" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #gint16</doc> + <type name="gint16" c:type="gint16"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">an int16 #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_int32" c:identifier="g_variant_get_int32" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #gint32</doc> + <type name="gint32" c:type="gint32"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">an int32 #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_int64" c:identifier="g_variant_get_int64" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #gint64</doc> + <type name="gint64" c:type="gint64"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">an int64 #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_maybe" c:identifier="g_variant_get_maybe" version="2.24"> + <doc xml:space="preserve">Given a maybe-typed #GVariant instance, extract its value. If the +value is Nothing, then this function returns %NULL.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the contents of @value, or %NULL</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a maybe-typed value</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_normal_form" c:identifier="g_variant_get_normal_form" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a trusted #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_objv" c:identifier="g_variant_get_objv" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="container"> + <doc xml:space="preserve">an array of constant strings</doc> + <array length="0" zero-terminated="1" c:type="const gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">an array of object paths #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the length of the result, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_size" c:identifier="g_variant_get_size" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the serialised size of @value</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_string" c:identifier="g_variant_get_string" version="2.24"> + <doc xml:space="preserve">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, will never be %NULL, and will never +contain nul bytes. + +If @length is non-%NULL then the length of the string (in bytes) is +returned there. For trusted values, this information is already +known. Untrusted values will be validated and, if valid, a strlen() will be +performed. If invalid, a default value will be returned — for +%G_VARIANT_TYPE_OBJECT_PATH, this is `"/"`, and for other types it is the +empty string. + +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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the constant string, UTF-8 encoded</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a string #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a pointer to a #gsize, + to store the length</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_strv" c:identifier="g_variant_get_strv" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="container"> + <doc xml:space="preserve">an array of constant strings</doc> + <array length="0" zero-terminated="1" c:type="const gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">an array of strings #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the length of the result, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_type" c:identifier="g_variant_get_type" version="2.24"> + <doc xml:space="preserve">Determines the type of @value. + +The return value is valid for the lifetime of @value and must not +be freed.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_type_string" c:identifier="g_variant_get_type_string" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the type string for the type of @value</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_uint16" c:identifier="g_variant_get_uint16" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #guint16</doc> + <type name="guint16" c:type="guint16"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a uint16 #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_uint32" c:identifier="g_variant_get_uint32" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #guint32</doc> + <type name="guint32" c:type="guint32"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a uint32 #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_uint64" c:identifier="g_variant_get_uint64" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #guint64</doc> + <type name="guint64" c:type="guint64"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a uint64 #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_va" c:identifier="g_variant_get_va" version="2.24" introspectable="0"> + <doc xml:space="preserve">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].</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="format_string" transfer-ownership="none"> + <doc xml:space="preserve">a string that is prefixed with a format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="endptr" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">location to store the end pointer, + or %NULL</doc> + <type name="utf8" c:type="const gchar**"/> + </parameter> + <parameter name="app" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #va_list</doc> + <type name="va_list" c:type="va_list*"/> + </parameter> + </parameters> + </method> + <method name="get_variant" c:identifier="g_variant_get_variant" version="2.24"> + <doc xml:space="preserve">Unboxes @value. The result is the #GVariant instance that was +contained in @value.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the item contained in the variant</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a variant #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="hash" c:identifier="g_variant_hash" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a hash value corresponding to @value</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a basic #GVariant value as a #gconstpointer</doc> + <type name="Variant" c:type="gconstpointer"/> + </instance-parameter> + </parameters> + </method> + <method name="is_container" c:identifier="g_variant_is_container" version="2.24"> + <doc xml:space="preserve">Checks if @value is a container.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @value is a container</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_floating" c:identifier="g_variant_is_floating" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether @value is floating</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_normal_form" c:identifier="g_variant_is_normal_form" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @value is in normal form</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_of_type" c:identifier="g_variant_is_of_type" version="2.24"> + <doc xml:space="preserve">Checks if a value has a type matching the provided type.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the type of @value matches @type</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant instance</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </method> + <method name="iter_new" c:identifier="g_variant_iter_new" version="2.24" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new heap-allocated #GVariantIter</doc> + <type name="VariantIter" c:type="GVariantIter*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a container #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="lookup" c:identifier="g_variant_lookup" version="2.28" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a value was unpacked</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="dictionary" transfer-ownership="none"> + <doc xml:space="preserve">a dictionary #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to look up in the dictionary</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="format_string" transfer-ownership="none"> + <doc xml:space="preserve">a GVariant format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the arguments to unpack the value into</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="lookup_value" c:identifier="g_variant_lookup_value" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the value of the dictionary key, or %NULL</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="dictionary" transfer-ownership="none"> + <doc xml:space="preserve">a dictionary #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to look up in the dictionary</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="expected_type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariantType, or %NULL</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </method> + <method name="n_children" c:identifier="g_variant_n_children" version="2.24"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of children in the container</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a container #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="print" c:identifier="g_variant_print" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated string holding the result.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="type_annotate" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if type information should be included in + the output</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="print_string" c:identifier="g_variant_print_string" version="2.24" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GString containing the string</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GString, or %NULL</doc> + <type name="String" c:type="GString*"/> + </parameter> + <parameter name="type_annotate" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if type information should be included in + the output</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_variant_ref" version="2.24"> + <doc xml:space="preserve">Increases the reference count of @value.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the same @value</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="ref_sink" c:identifier="g_variant_ref_sink" version="2.24"> + <doc xml:space="preserve">#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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the same @value</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="store" c:identifier="g_variant_store" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the #GVariant to store</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">the location to store the serialised data at</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="take_ref" c:identifier="g_variant_take_ref"> + <doc xml:space="preserve">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 always 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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the same @value</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_variant_unref" version="2.24"> + <doc xml:space="preserve">Decreases the reference count of @value. When its reference count +drops to 0, the memory used by the variant is freed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </instance-parameter> + </parameters> + </method> + <function name="is_object_path" c:identifier="g_variant_is_object_path" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @string is a D-Bus object path</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a normal C nul-terminated string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="is_signature" c:identifier="g_variant_is_signature" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @string is a D-Bus type signature</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a normal C nul-terminated string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="parse" c:identifier="g_variant_parse" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a non-floating reference to a #GVariant, or %NULL</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariantType, or %NULL</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="text" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a GVariant in text form</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="limit" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to the end of @text, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="endptr" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a location to store the end pointer, or %NULL</doc> + <type name="utf8" c:type="const gchar**"/> + </parameter> + </parameters> + </function> + <function name="parse_error_print_context" c:identifier="g_variant_parse_error_print_context" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the printed message</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">a #GError from the #GVariantParseError domain</doc> + <type name="Error" c:type="GError*"/> + </parameter> + <parameter name="source_str" transfer-ownership="none"> + <doc xml:space="preserve">the string that was given to the parser</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="parse_error_quark" c:identifier="g_variant_parse_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="parser_get_error_quark" c:identifier="g_variant_parser_get_error_quark" deprecated="1"> + <doc xml:space="preserve">Same as g_variant_error_quark().</doc> + <doc-deprecated xml:space="preserve">Use g_variant_parse_error_quark() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + </record> + <record name="VariantBuilder" c:type="GVariantBuilder" glib:type-name="GVariantBuilder" glib:get-type="g_variant_builder_get_type" c:symbol-prefix="variant_builder"> + <doc xml:space="preserve">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.</doc> + <union name="u" c:type="u"> + <record name="s" c:type="s"> + <field name="partial_magic" writable="1"> + <type name="gsize" c:type="gsize"/> + </field> + <field name="type" writable="1"> + <type name="VariantType" c:type="const GVariantType*"/> + </field> + <field name="y" writable="1"> + <array zero-terminated="0" fixed-size="14"> + <type name="gsize" c:type="gsize"/> + </array> + </field> + </record> + <field name="x" writable="1"> + <array zero-terminated="0" fixed-size="16"> + <type name="gsize" c:type="gsize"/> + </array> + </field> + </union> + <constructor name="new" c:identifier="g_variant_builder_new" version="2.24"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GVariantBuilder</doc> + <type name="VariantBuilder" c:type="GVariantBuilder*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a container type</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </constructor> + <method name="add" c:identifier="g_variant_builder_add" version="2.24" introspectable="0"> + <doc xml:space="preserve">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); +} +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="builder" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantBuilder</doc> + <type name="VariantBuilder" c:type="GVariantBuilder*"/> + </instance-parameter> + <parameter name="format_string" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant varargs format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">arguments, as per @format_string</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="add_parsed" c:identifier="g_variant_builder_add_parsed" version="2.26" introspectable="0"> + <doc xml:space="preserve">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); +} +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="builder" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantBuilder</doc> + <type name="VariantBuilder" c:type="GVariantBuilder*"/> + </instance-parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a text format #GVariant</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">arguments as per @format</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="add_value" c:identifier="g_variant_builder_add_value" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="builder" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantBuilder</doc> + <type name="VariantBuilder" c:type="GVariantBuilder*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="clear" c:identifier="g_variant_builder_clear" version="2.24" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="builder" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantBuilder</doc> + <type name="VariantBuilder" c:type="GVariantBuilder*"/> + </instance-parameter> + </parameters> + </method> + <method name="close" c:identifier="g_variant_builder_close" version="2.24"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="builder" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantBuilder</doc> + <type name="VariantBuilder" c:type="GVariantBuilder*"/> + </instance-parameter> + </parameters> + </method> + <method name="end" c:identifier="g_variant_builder_end" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a new, floating, #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="builder" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantBuilder</doc> + <type name="VariantBuilder" c:type="GVariantBuilder*"/> + </instance-parameter> + </parameters> + </method> + <method name="init" c:identifier="g_variant_builder_init" version="2.24" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="builder" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantBuilder</doc> + <type name="VariantBuilder" c:type="GVariantBuilder*"/> + </instance-parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a container type</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </method> + <method name="open" c:identifier="g_variant_builder_open" version="2.24"> + <doc xml:space="preserve">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); +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="builder" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantBuilder</doc> + <type name="VariantBuilder" c:type="GVariantBuilder*"/> + </instance-parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">the #GVariantType of the container</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_variant_builder_ref" version="2.24"> + <doc xml:space="preserve">Increases the reference count on @builder. + +Don't call this on stack-allocated #GVariantBuilder instances or bad +things will happen.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new reference to @builder</doc> + <type name="VariantBuilder" c:type="GVariantBuilder*"/> + </return-value> + <parameters> + <instance-parameter name="builder" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantBuilder allocated by g_variant_builder_new()</doc> + <type name="VariantBuilder" c:type="GVariantBuilder*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_variant_builder_unref" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="builder" transfer-ownership="full"> + <doc xml:space="preserve">a #GVariantBuilder allocated by g_variant_builder_new()</doc> + <type name="VariantBuilder" c:type="GVariantBuilder*"/> + </instance-parameter> + </parameters> + </method> + </record> + <enumeration name="VariantClass" version="2.24" c:type="GVariantClass"> + <doc xml:space="preserve">The range of possible top-level types of #GVariant instances.</doc> + <member name="boolean" value="98" c:identifier="G_VARIANT_CLASS_BOOLEAN"> + <doc xml:space="preserve">The #GVariant is a boolean.</doc> + </member> + <member name="byte" value="121" c:identifier="G_VARIANT_CLASS_BYTE"> + <doc xml:space="preserve">The #GVariant is a byte.</doc> + </member> + <member name="int16" value="110" c:identifier="G_VARIANT_CLASS_INT16"> + <doc xml:space="preserve">The #GVariant is a signed 16 bit integer.</doc> + </member> + <member name="uint16" value="113" c:identifier="G_VARIANT_CLASS_UINT16"> + <doc xml:space="preserve">The #GVariant is an unsigned 16 bit integer.</doc> + </member> + <member name="int32" value="105" c:identifier="G_VARIANT_CLASS_INT32"> + <doc xml:space="preserve">The #GVariant is a signed 32 bit integer.</doc> + </member> + <member name="uint32" value="117" c:identifier="G_VARIANT_CLASS_UINT32"> + <doc xml:space="preserve">The #GVariant is an unsigned 32 bit integer.</doc> + </member> + <member name="int64" value="120" c:identifier="G_VARIANT_CLASS_INT64"> + <doc xml:space="preserve">The #GVariant is a signed 64 bit integer.</doc> + </member> + <member name="uint64" value="116" c:identifier="G_VARIANT_CLASS_UINT64"> + <doc xml:space="preserve">The #GVariant is an unsigned 64 bit integer.</doc> + </member> + <member name="handle" value="104" c:identifier="G_VARIANT_CLASS_HANDLE"> + <doc xml:space="preserve">The #GVariant is a file handle index.</doc> + </member> + <member name="double" value="100" c:identifier="G_VARIANT_CLASS_DOUBLE"> + <doc xml:space="preserve">The #GVariant is a double precision floating + point value.</doc> + </member> + <member name="string" value="115" c:identifier="G_VARIANT_CLASS_STRING"> + <doc xml:space="preserve">The #GVariant is a normal string.</doc> + </member> + <member name="object_path" value="111" c:identifier="G_VARIANT_CLASS_OBJECT_PATH"> + <doc xml:space="preserve">The #GVariant is a D-Bus object path + string.</doc> + </member> + <member name="signature" value="103" c:identifier="G_VARIANT_CLASS_SIGNATURE"> + <doc xml:space="preserve">The #GVariant is a D-Bus signature string.</doc> + </member> + <member name="variant" value="118" c:identifier="G_VARIANT_CLASS_VARIANT"> + <doc xml:space="preserve">The #GVariant is a variant.</doc> + </member> + <member name="maybe" value="109" c:identifier="G_VARIANT_CLASS_MAYBE"> + <doc xml:space="preserve">The #GVariant is a maybe-typed value.</doc> + </member> + <member name="array" value="97" c:identifier="G_VARIANT_CLASS_ARRAY"> + <doc xml:space="preserve">The #GVariant is an array.</doc> + </member> + <member name="tuple" value="40" c:identifier="G_VARIANT_CLASS_TUPLE"> + <doc xml:space="preserve">The #GVariant is a tuple.</doc> + </member> + <member name="dict_entry" value="123" c:identifier="G_VARIANT_CLASS_DICT_ENTRY"> + <doc xml:space="preserve">The #GVariant is a dictionary entry.</doc> + </member> + </enumeration> + <record name="VariantDict" c:type="GVariantDict" version="2.40" glib:type-name="GVariantDict" glib:get-type="g_variant_dict_get_type" c:symbol-prefix="variant_dict"> + <doc xml:space="preserve">#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; + } +]|</doc> + <union name="u" c:type="u"> + <record name="s" c:type="s"> + <field name="asv" writable="1"> + <type name="Variant" c:type="GVariant*"/> + </field> + <field name="partial_magic" writable="1"> + <type name="gsize" c:type="gsize"/> + </field> + <field name="y" writable="1"> + <array zero-terminated="0" fixed-size="14"> + <type name="gsize" c:type="gsize"/> + </array> + </field> + </record> + <field name="x" writable="1"> + <array zero-terminated="0" fixed-size="16"> + <type name="gsize" c:type="gsize"/> + </array> + </field> + </union> + <constructor name="new" c:identifier="g_variant_dict_new" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GVariantDict</doc> + <type name="VariantDict" c:type="GVariantDict*"/> + </return-value> + <parameters> + <parameter name="from_asv" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the #GVariant with which to initialise the + dictionary</doc> + <type name="Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </constructor> + <method name="clear" c:identifier="g_variant_dict_clear" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="dict" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantDict</doc> + <type name="VariantDict" c:type="GVariantDict*"/> + </instance-parameter> + </parameters> + </method> + <method name="contains" c:identifier="g_variant_dict_contains" version="2.40"> + <doc xml:space="preserve">Checks if @key exists in @dict.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @key is in @dict</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="dict" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantDict</doc> + <type name="VariantDict" c:type="GVariantDict*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to look up in the dictionary</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="end" c:identifier="g_variant_dict_end" version="2.40"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a new, floating, #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="dict" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantDict</doc> + <type name="VariantDict" c:type="GVariantDict*"/> + </instance-parameter> + </parameters> + </method> + <method name="init" c:identifier="g_variant_dict_init" version="2.40" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="dict" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantDict</doc> + <type name="VariantDict" c:type="GVariantDict*"/> + </instance-parameter> + <parameter name="from_asv" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the initial value for @dict</doc> + <type name="Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="insert" c:identifier="g_variant_dict_insert" version="2.40" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="dict" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantDict</doc> + <type name="VariantDict" c:type="GVariantDict*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to insert a value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="format_string" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant varargs format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">arguments, as per @format_string</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="insert_value" c:identifier="g_variant_dict_insert_value" version="2.40"> + <doc xml:space="preserve">Inserts (or replaces) a key in a #GVariantDict. + +@value is consumed if it is floating.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="dict" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantDict</doc> + <type name="VariantDict" c:type="GVariantDict*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to insert a value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value to insert</doc> + <type name="Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="lookup" c:identifier="g_variant_dict_lookup" version="2.40" introspectable="0"> + <doc xml:space="preserve">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].</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a value was unpacked</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="dict" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantDict</doc> + <type name="VariantDict" c:type="GVariantDict*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to look up in the dictionary</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="format_string" transfer-ownership="none"> + <doc xml:space="preserve">a GVariant format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the arguments to unpack the value into</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="lookup_value" c:identifier="g_variant_dict_lookup_value" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the value of the dictionary key, or %NULL</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="dict" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantDict</doc> + <type name="VariantDict" c:type="GVariantDict*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to look up in the dictionary</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="expected_type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariantType, or %NULL</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_variant_dict_ref" version="2.40"> + <doc xml:space="preserve">Increases the reference count on @dict. + +Don't call this on stack-allocated #GVariantDict instances or bad +things will happen.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new reference to @dict</doc> + <type name="VariantDict" c:type="GVariantDict*"/> + </return-value> + <parameters> + <instance-parameter name="dict" transfer-ownership="none"> + <doc xml:space="preserve">a heap-allocated #GVariantDict</doc> + <type name="VariantDict" c:type="GVariantDict*"/> + </instance-parameter> + </parameters> + </method> + <method name="remove" c:identifier="g_variant_dict_remove" version="2.40"> + <doc xml:space="preserve">Removes a key and its associated value from a #GVariantDict.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key was found and removed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="dict" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantDict</doc> + <type name="VariantDict" c:type="GVariantDict*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to remove</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_variant_dict_unref" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="dict" transfer-ownership="full"> + <doc xml:space="preserve">a heap-allocated #GVariantDict</doc> + <type name="VariantDict" c:type="GVariantDict*"/> + </instance-parameter> + </parameters> + </method> + </record> + <record name="VariantIter" c:type="GVariantIter" introspectable="0"> + <doc xml:space="preserve">#GVariantIter is an opaque data structure and can only be accessed +using the following functions.</doc> + <field name="x" readable="0" private="1"> + <array zero-terminated="0" fixed-size="16"> + <type name="gsize" c:type="gsize"/> + </array> + </field> + <method name="copy" c:identifier="g_variant_iter_copy" version="2.24" introspectable="0"> + <doc xml:space="preserve">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 related only when g_variant_iter_free() is called.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new heap-allocated #GVariantIter</doc> + <type name="VariantIter" c:type="GVariantIter*"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantIter</doc> + <type name="VariantIter" c:type="GVariantIter*"/> + </instance-parameter> + </parameters> + </method> + <method name="free" c:identifier="g_variant_iter_free" version="2.24"> + <doc xml:space="preserve">Frees a heap-allocated #GVariantIter. Only call this function on +iterators that were returned by g_variant_iter_new() or +g_variant_iter_copy().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="full"> + <doc xml:space="preserve">a heap-allocated #GVariantIter</doc> + <type name="VariantIter" c:type="GVariantIter*"/> + </instance-parameter> + </parameters> + </method> + <method name="init" c:identifier="g_variant_iter_init" version="2.24" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of items in @value</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GVariantIter</doc> + <type name="VariantIter" c:type="GVariantIter*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a container #GVariant</doc> + <type name="Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="loop" c:identifier="g_variant_iter_loop" version="2.24" introspectable="0"> + <doc xml:space="preserve">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].</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a value was unpacked, or %FALSE if there was no + value</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantIter</doc> + <type name="VariantIter" c:type="GVariantIter*"/> + </instance-parameter> + <parameter name="format_string" transfer-ownership="none"> + <doc xml:space="preserve">a GVariant format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the arguments to unpack the value into</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="n_children" c:identifier="g_variant_iter_n_children" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of children in the container</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantIter</doc> + <type name="VariantIter" c:type="GVariantIter*"/> + </instance-parameter> + </parameters> + </method> + <method name="next" c:identifier="g_variant_iter_next" version="2.24" introspectable="0"> + <doc xml:space="preserve">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].</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a value was unpacked, or %FALSE if there as no value</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantIter</doc> + <type name="VariantIter" c:type="GVariantIter*"/> + </instance-parameter> + <parameter name="format_string" transfer-ownership="none"> + <doc xml:space="preserve">a GVariant format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the arguments to unpack the value into</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="next_value" c:identifier="g_variant_iter_next_value" version="2.24"> + <doc xml:space="preserve">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); + } + } +]|</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GVariant, or %NULL</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantIter</doc> + <type name="VariantIter" c:type="GVariantIter*"/> + </instance-parameter> + </parameters> + </method> + </record> + <enumeration name="VariantParseError" c:type="GVariantParseError" glib:error-domain="g-variant-parse-error-quark"> + <doc xml:space="preserve">Error codes returned by parsing text-format GVariants.</doc> + <member name="failed" value="0" c:identifier="G_VARIANT_PARSE_ERROR_FAILED"> + <doc xml:space="preserve">generic error (unused)</doc> + </member> + <member name="basic_type_expected" value="1" c:identifier="G_VARIANT_PARSE_ERROR_BASIC_TYPE_EXPECTED"> + <doc xml:space="preserve">a non-basic #GVariantType was given where a basic type was expected</doc> + </member> + <member name="cannot_infer_type" value="2" c:identifier="G_VARIANT_PARSE_ERROR_CANNOT_INFER_TYPE"> + <doc xml:space="preserve">cannot infer the #GVariantType</doc> + </member> + <member name="definite_type_expected" value="3" c:identifier="G_VARIANT_PARSE_ERROR_DEFINITE_TYPE_EXPECTED"> + <doc xml:space="preserve">an indefinite #GVariantType was given where a definite type was expected</doc> + </member> + <member name="input_not_at_end" value="4" c:identifier="G_VARIANT_PARSE_ERROR_INPUT_NOT_AT_END"> + <doc xml:space="preserve">extra data after parsing finished</doc> + </member> + <member name="invalid_character" value="5" c:identifier="G_VARIANT_PARSE_ERROR_INVALID_CHARACTER"> + <doc xml:space="preserve">invalid character in number or unicode escape</doc> + </member> + <member name="invalid_format_string" value="6" c:identifier="G_VARIANT_PARSE_ERROR_INVALID_FORMAT_STRING"> + <doc xml:space="preserve">not a valid #GVariant format string</doc> + </member> + <member name="invalid_object_path" value="7" c:identifier="G_VARIANT_PARSE_ERROR_INVALID_OBJECT_PATH"> + <doc xml:space="preserve">not a valid object path</doc> + </member> + <member name="invalid_signature" value="8" c:identifier="G_VARIANT_PARSE_ERROR_INVALID_SIGNATURE"> + <doc xml:space="preserve">not a valid type signature</doc> + </member> + <member name="invalid_type_string" value="9" c:identifier="G_VARIANT_PARSE_ERROR_INVALID_TYPE_STRING"> + <doc xml:space="preserve">not a valid #GVariant type string</doc> + </member> + <member name="no_common_type" value="10" c:identifier="G_VARIANT_PARSE_ERROR_NO_COMMON_TYPE"> + <doc xml:space="preserve">could not find a common type for array entries</doc> + </member> + <member name="number_out_of_range" value="11" c:identifier="G_VARIANT_PARSE_ERROR_NUMBER_OUT_OF_RANGE"> + <doc xml:space="preserve">the numerical value is out of range of the given type</doc> + </member> + <member name="number_too_big" value="12" c:identifier="G_VARIANT_PARSE_ERROR_NUMBER_TOO_BIG"> + <doc xml:space="preserve">the numerical value is out of range for any type</doc> + </member> + <member name="type_error" value="13" c:identifier="G_VARIANT_PARSE_ERROR_TYPE_ERROR"> + <doc xml:space="preserve">cannot parse as variant of the specified type</doc> + </member> + <member name="unexpected_token" value="14" c:identifier="G_VARIANT_PARSE_ERROR_UNEXPECTED_TOKEN"> + <doc xml:space="preserve">an unexpected token was encountered</doc> + </member> + <member name="unknown_keyword" value="15" c:identifier="G_VARIANT_PARSE_ERROR_UNKNOWN_KEYWORD"> + <doc xml:space="preserve">an unknown keyword was encountered</doc> + </member> + <member name="unterminated_string_constant" value="16" c:identifier="G_VARIANT_PARSE_ERROR_UNTERMINATED_STRING_CONSTANT"> + <doc xml:space="preserve">unterminated string constant</doc> + </member> + <member name="value_expected" value="17" c:identifier="G_VARIANT_PARSE_ERROR_VALUE_EXPECTED"> + <doc xml:space="preserve">no value given</doc> + </member> + <member name="recursion" value="18" c:identifier="G_VARIANT_PARSE_ERROR_RECURSION"> + <doc xml:space="preserve">variant was too deeply nested; #GVariant is only guaranteed to handle nesting up to 64 levels (Since: 2.64)</doc> + </member> + </enumeration> + <record name="VariantType" c:type="GVariantType" glib:type-name="GVariantType" glib:get-type="g_variant_type_get_gtype" c:symbol-prefix="variant_type"> + <doc xml:space="preserve">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 D-Bus. 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.</doc> + <constructor name="new" c:identifier="g_variant_type_new" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GVariantType</doc> + <type name="VariantType" c:type="GVariantType*"/> + </return-value> + <parameters> + <parameter name="type_string" transfer-ownership="none"> + <doc xml:space="preserve">a valid GVariant type string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_array" c:identifier="g_variant_type_new_array"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new array #GVariantType + +Since 2.24</doc> + <type name="VariantType" c:type="GVariantType*"/> + </return-value> + <parameters> + <parameter name="element" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_dict_entry" c:identifier="g_variant_type_new_dict_entry"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new dictionary entry #GVariantType + +Since 2.24</doc> + <type name="VariantType" c:type="GVariantType*"/> + </return-value> + <parameters> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a basic #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_maybe" c:identifier="g_variant_type_new_maybe"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new maybe #GVariantType + +Since 2.24</doc> + <type name="VariantType" c:type="GVariantType*"/> + </return-value> + <parameters> + <parameter name="element" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_tuple" c:identifier="g_variant_type_new_tuple"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new tuple #GVariantType + +Since 2.24</doc> + <type name="VariantType" c:type="GVariantType*"/> + </return-value> + <parameters> + <parameter name="items" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GVariantTypes, one for each item</doc> + <array length="1" zero-terminated="0" c:type="const GVariantType* const*"> + <type name="VariantType" c:type="GVariantType*"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @items, or -1</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </constructor> + <method name="copy" c:identifier="g_variant_type_copy"> + <doc xml:space="preserve">Makes a copy of a #GVariantType. It is appropriate to call +g_variant_type_free() on the return value. @type may not be %NULL.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GVariantType + +Since 2.24</doc> + <type name="VariantType" c:type="GVariantType*"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="dup_string" c:identifier="g_variant_type_dup_string"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the corresponding type string + +Since 2.24</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="element" c:identifier="g_variant_type_element"> + <doc xml:space="preserve">Determines the element type of an array or maybe type. + +This function may only be used with array or maybe types.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the element type of @type + +Since 2.24</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">an array or maybe #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="equal" c:identifier="g_variant_type_equal"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @type1 and @type2 are exactly equal + +Since 2.24</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="type1" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="gconstpointer"/> + </instance-parameter> + <parameter name="type2" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="first" c:identifier="g_variant_type_first"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the first item type of @type, or %NULL + +Since 2.24</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a tuple or dictionary entry #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="free" c:identifier="g_variant_type_free"> + <doc xml:space="preserve">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</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariantType, or %NULL</doc> + <type name="VariantType" c:type="GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_string_length" c:identifier="g_variant_type_get_string_length"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the length of the corresponding type string + +Since 2.24</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="hash" c:identifier="g_variant_type_hash"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the hash value + +Since 2.24</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="gconstpointer"/> + </instance-parameter> + </parameters> + </method> + <method name="is_array" c:identifier="g_variant_type_is_array"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @type is an array type + +Since 2.24</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_basic" c:identifier="g_variant_type_is_basic"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @type is a basic type + +Since 2.24</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_container" c:identifier="g_variant_type_is_container"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @type is a container type + +Since 2.24</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_definite" c:identifier="g_variant_type_is_definite"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @type is definite + +Since 2.24</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_dict_entry" c:identifier="g_variant_type_is_dict_entry"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @type is a dictionary entry type + +Since 2.24</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_maybe" c:identifier="g_variant_type_is_maybe"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @type is a maybe type + +Since 2.24</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_subtype_of" c:identifier="g_variant_type_is_subtype_of"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @type is a subtype of @supertype + +Since 2.24</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + <parameter name="supertype" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </method> + <method name="is_tuple" c:identifier="g_variant_type_is_tuple"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @type is a tuple type + +Since 2.24</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_variant" c:identifier="g_variant_type_is_variant"> + <doc xml:space="preserve">Determines if the given @type is the variant type.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @type is the variant type + +Since 2.24</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="key" c:identifier="g_variant_type_key"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the key type of the dictionary entry + +Since 2.24</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a dictionary entry #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="n_items" c:identifier="g_variant_type_n_items"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of items in @type + +Since 2.24</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a tuple or dictionary entry #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="next" c:identifier="g_variant_type_next"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the next #GVariantType after @type, or %NULL + +Since 2.24</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType from a previous call</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="peek_string" c:identifier="g_variant_type_peek_string" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the corresponding type string (not nul-terminated) + +Since 2.24</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <method name="value" c:identifier="g_variant_type_value"> + <doc xml:space="preserve">Determines the value type of a dictionary entry type. + +This function may only be used with a dictionary entry type.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value type of the dictionary entry + +Since 2.24</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <instance-parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a dictionary entry #GVariantType</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </instance-parameter> + </parameters> + </method> + <function name="checked_" c:identifier="g_variant_type_checked_"> + <return-value transfer-ownership="none"> + <type name="VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <parameter name="arg0" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="string_get_depth_" c:identifier="g_variant_type_string_get_depth_"> + <return-value transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="type_string" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="string_is_valid" c:identifier="g_variant_type_string_is_valid"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @type_string is exactly one valid type string + +Since 2.24</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="type_string" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to any string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="string_scan" c:identifier="g_variant_type_string_scan" version="2.24"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a valid type string was found</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to any string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="limit" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the end of @string, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="endptr" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the end pointer, or %NULL</doc> + <type name="utf8" c:type="const gchar**"/> + </parameter> + </parameters> + </function> + </record> + <callback name="VoidFunc" c:type="GVoidFunc"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + <function-macro name="WIN32_DLLMAIN_FOR_DLL_NAME" c:identifier="G_WIN32_DLLMAIN_FOR_DLL_NAME" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="static"> + <doc xml:space="preserve">empty or "static"</doc> + </parameter> + <parameter name="dll_name"> + <doc xml:space="preserve">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</doc> + </parameter> + </parameters> + </function-macro> + <constant name="WIN32_MSG_HANDLE" value="19981206" c:type="G_WIN32_MSG_HANDLE"> + <type name="gint" c:type="gint"/> + </constant> + <function name="access" c:identifier="g_access" version="2.8"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">zero if the pathname refers to an existing file system + object that has all the tested permissions, or -1 otherwise + or on error.</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">a pathname in the GLib file name encoding + (UTF-8 on Windows)</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve">as in access()</doc> + <type name="gint" c:type="int"/> + </parameter> + </parameters> + </function> + <function-macro name="alloca" c:identifier="g_alloca" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="size"> + <doc xml:space="preserve">number of bytes to allocate.</doc> + </parameter> + </parameters> + </function-macro> + <docsection name="arcbox"> + <doc xml:space="preserve">An "atomically reference counted box", or "ArcBox", is an opaque wrapper +data type that is guaranteed to be as big as the size of a given data type, +and which augments the given data type with thread safe reference counting +semantics for its memory management. + +ArcBox is useful if you have a plain old data type, like a structure +typically placed on the stack, and you wish to provide additional API +to use it on the heap; or if you want to implement a new type to be +passed around by reference without necessarily implementing copy/free +semantics or your own reference counting. + +The typical use is: + +|[<!-- language="C" --> +typedef struct { + char *name; + char *address; + char *city; + char *state; + int age; +} Person; + +Person * +person_new (void) +{ + return g_atomic_rc_box_new0 (Person); +} +]| + +Every time you wish to acquire a reference on the memory, you should +call g_atomic_rc_box_acquire(); similarly, when you wish to release a reference +you should call g_atomic_rc_box_release(): + +|[<!-- language="C" --> +// Add a Person to the Database; the Database acquires ownership +// of the Person instance +void +add_person_to_database (Database *db, Person *p) +{ + db->persons = g_list_prepend (db->persons, g_atomic_rc_box_acquire (p)); +} + +// Removes a Person from the Database; the reference acquired by +// add_person_to_database() is released here +void +remove_person_from_database (Database *db, Person *p) +{ + db->persons = g_list_remove (db->persons, p); + g_atomic_rc_box_release (p); +} +]| + +If you have additional memory allocated inside the structure, you can +use g_atomic_rc_box_release_full(), which takes a function pointer, which +will be called if the reference released was the last: + +|[<!-- language="C" --> +void +person_clear (Person *p) +{ + g_free (p->name); + g_free (p->address); + g_free (p->city); + g_free (p->state); +} + +void +remove_person_from_database (Database *db, Person *p) +{ + db->persons = g_list_remove (db->persons, p); + g_atomic_rc_box_release_full (p, (GDestroyNotify) person_clear); +} +]| + +If you wish to transfer the ownership of a reference counted data +type without increasing the reference count, you can use g_steal_pointer(): + +|[<!-- language="C" --> + Person *p = g_atomic_rc_box_new (Person); + + fill_person_details (p); + + add_person_to_database (db, g_steal_pointer (&p)); +]| + +## Thread safety + +The reference counting operations on data allocated using g_atomic_rc_box_alloc(), +g_atomic_rc_box_new(), and g_atomic_rc_box_dup() are guaranteed to be atomic, and thus +can be safely be performed by different threads. It is important to note that +only the reference acquisition and release are atomic; changes to the content +of the data are your responsibility. + +## Automatic pointer clean up + +If you want to add g_autoptr() support to your plain old data type through +reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and +g_atomic_rc_box_release(): + +|[<!-- language="C" --> +G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_atomic_rc_box_release) +]| + +If you need to clear the contents of the data, you will need to use an +ancillary function that calls g_rc_box_release_full(): + +|[<!-- language="C" --> +static void +my_data_struct_release (MyDataStruct *data) +{ + // my_data_struct_clear() is defined elsewhere + g_atomic_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear); +} + +G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release) +]|</doc> + </docsection> + <function-macro name="array_append_val" c:identifier="g_array_append_val" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="a"> + <doc xml:space="preserve">a #GArray</doc> + </parameter> + <parameter name="v"> + <doc xml:space="preserve">the value to append to the #GArray</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="array_index" c:identifier="g_array_index" introspectable="0"> + <doc xml:space="preserve">Returns the element of a #GArray at the given index. The return +value is cast to the given type. This is the main way to read or write an +element in a #GArray. + +Writing an element is typically done by reference, as in the following +example. This example gets a pointer to an element in a #GArray, and then +writes to a field in it: +|[<!-- 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); + event->start_time = g_get_current_time (); +]| + +This example reads from and writes to an array of integers: +|[<!-- language="C" --> + g_autoptr(GArray) int_array = g_array_new (FALSE, FALSE, sizeof (guint)); + for (guint i = 0; i < 10; i++) + g_array_append_val (int_array, i); + + guint *my_int = &g_array_index (int_array, guint, 1); + g_print ("Int at index 1 is %u; decrementing it\n", *my_int); + *my_int = *my_int - 1; +]|</doc> + <parameters> + <parameter name="a"> + <doc xml:space="preserve">a #GArray</doc> + </parameter> + <parameter name="t"> + <doc xml:space="preserve">the type of the elements</doc> + </parameter> + <parameter name="i"> + <doc xml:space="preserve">the index of the element to return</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="array_insert_val" c:identifier="g_array_insert_val" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="a"> + <doc xml:space="preserve">a #GArray</doc> + </parameter> + <parameter name="i"> + <doc xml:space="preserve">the index to place the element at</doc> + </parameter> + <parameter name="v"> + <doc xml:space="preserve">the value to insert into the array</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="array_prepend_val" c:identifier="g_array_prepend_val" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="a"> + <doc xml:space="preserve">a #GArray</doc> + </parameter> + <parameter name="v"> + <doc xml:space="preserve">the value to prepend to the #GArray</doc> + </parameter> + </parameters> + </function-macro> + <docsection name="arrays"> + <doc xml:space="preserve">Arrays are similar to standard C arrays, except that they grow +automatically as elements are added. + +Array elements can be of any size (though all elements of one array +are the same size), and the array can be automatically cleared to +'0's and zero-terminated. + +To create a new array use g_array_new(). + +To add elements to an array with a cost of O(n) at worst, use +g_array_append_val(), g_array_append_vals(), g_array_prepend_val(), +g_array_prepend_vals(), g_array_insert_val() and g_array_insert_vals(). + +To access an element of an array in O(1) (to read it or to write it), +use g_array_index(). + +To set the size of an array, use g_array_set_size(). + +To free an array, use g_array_unref() or g_array_free(). + +All the sort functions are internally calling a quick-sort (or similar) +function with an average cost of O(n log(n)) and a worst case +cost of O(n^2). + +Here is an example that stores integers in a #GArray: +|[<!-- language="C" --> + GArray *garray; + gint i; + // We create a new array to store gint values. + // We don't want it zero-terminated or cleared to 0's. + garray = g_array_new (FALSE, FALSE, sizeof (gint)); + for (i = 0; i < 10000; i++) + g_array_append_val (garray, i); + for (i = 0; i < 10000; i++) + if (g_array_index (garray, gint, i) != i) + g_print ("ERROR: got %d instead of %d\n", + g_array_index (garray, gint, i), i); + g_array_free (garray, TRUE); +]|</doc> + </docsection> + <docsection name="arrays_byte"> + <doc xml:space="preserve">#GByteArray is a mutable array of bytes based on #GArray, to provide arrays +of bytes which grow automatically as elements are added. + +To create a new #GByteArray use g_byte_array_new(). To add elements to a +#GByteArray, use g_byte_array_append(), and g_byte_array_prepend(). + +To set the size of a #GByteArray, use g_byte_array_set_size(). + +To free a #GByteArray, use g_byte_array_free(). + +An example for using a #GByteArray: +|[<!-- language="C" --> + GByteArray *gbarray; + gint i; + + gbarray = g_byte_array_new (); + for (i = 0; i < 10000; i++) + g_byte_array_append (gbarray, (guint8*) "abcd", 4); + + for (i = 0; i < 10000; i++) + { + g_assert (gbarray->data[4*i] == 'a'); + g_assert (gbarray->data[4*i+1] == 'b'); + g_assert (gbarray->data[4*i+2] == 'c'); + g_assert (gbarray->data[4*i+3] == 'd'); + } + + g_byte_array_free (gbarray, TRUE); +]| + +See #GBytes if you are interested in an immutable object representing a +sequence of bytes.</doc> + </docsection> + <docsection name="arrays_pointer"> + <doc xml:space="preserve">Pointer Arrays are similar to Arrays but are used only for storing +pointers. + +If you remove elements from the array, elements at the end of the +array are moved into the space previously occupied by the removed +element. This means that you should not rely on the index of particular +elements remaining the same. You should also be careful when deleting +elements while iterating over the array. + +To create a pointer array, use g_ptr_array_new(). + +To add elements to a pointer array, use g_ptr_array_add(). + +To remove elements from a pointer array, use g_ptr_array_remove(), +g_ptr_array_remove_index() or g_ptr_array_remove_index_fast(). + +To access an element of a pointer array, use g_ptr_array_index(). + +To set the size of a pointer array, use g_ptr_array_set_size(). + +To free a pointer array, use g_ptr_array_free(). + +An example using a #GPtrArray: +|[<!-- language="C" --> + GPtrArray *array; + gchar *string1 = "one"; + gchar *string2 = "two"; + gchar *string3 = "three"; + + array = g_ptr_array_new (); + g_ptr_array_add (array, (gpointer) string1); + g_ptr_array_add (array, (gpointer) string2); + g_ptr_array_add (array, (gpointer) string3); + + if (g_ptr_array_index (array, 0) != (gpointer) string1) + g_print ("ERROR: got %p instead of %p\n", + g_ptr_array_index (array, 0), string1); + + g_ptr_array_free (array, TRUE); +]|</doc> + </docsection> + <function name="ascii_digit_value" c:identifier="g_ascii_digit_value"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">If @c is a decimal digit (according to g_ascii_isdigit()), + its numeric value. Otherwise, -1.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">an ASCII character</doc> + <type name="gchar" c:type="gchar"/> + </parameter> + </parameters> + </function> + <function name="ascii_dtostr" c:identifier="g_ascii_dtostr"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">The pointer to the buffer with the converted string.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">A buffer to place the resulting string in</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="buf_len" transfer-ownership="none"> + <doc xml:space="preserve">The length of the buffer.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="d" transfer-ownership="none"> + <doc xml:space="preserve">The #gdouble to convert</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + </parameters> + </function> + <function name="ascii_formatd" c:identifier="g_ascii_formatd"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">The pointer to the buffer with the converted string.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">A buffer to place the resulting string in</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="buf_len" transfer-ownership="none"> + <doc xml:space="preserve">The length of the buffer.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">The printf()-style format to use for the + code to use for converting.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="d" transfer-ownership="none"> + <doc xml:space="preserve">The #gdouble to convert</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + </parameters> + </function> + <function-macro name="ascii_isalnum" c:identifier="g_ascii_isalnum" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="c"> + <doc xml:space="preserve">any character</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="ascii_isalpha" c:identifier="g_ascii_isalpha" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="c"> + <doc xml:space="preserve">any character</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="ascii_iscntrl" c:identifier="g_ascii_iscntrl" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="c"> + <doc xml:space="preserve">any character</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="ascii_isdigit" c:identifier="g_ascii_isdigit" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="c"> + <doc xml:space="preserve">any character</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="ascii_isgraph" c:identifier="g_ascii_isgraph" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="c"> + <doc xml:space="preserve">any character</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="ascii_islower" c:identifier="g_ascii_islower" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="c"> + <doc xml:space="preserve">any character</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="ascii_isprint" c:identifier="g_ascii_isprint" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="c"> + <doc xml:space="preserve">any character</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="ascii_ispunct" c:identifier="g_ascii_ispunct" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="c"> + <doc xml:space="preserve">any character</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="ascii_isspace" c:identifier="g_ascii_isspace" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="c"> + <doc xml:space="preserve">any character</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="ascii_isupper" c:identifier="g_ascii_isupper" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="c"> + <doc xml:space="preserve">any character</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="ascii_isxdigit" c:identifier="g_ascii_isxdigit" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="c"> + <doc xml:space="preserve">any character</doc> + </parameter> + </parameters> + </function-macro> + <function name="ascii_strcasecmp" c:identifier="g_ascii_strcasecmp"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">0 if the strings match, a negative value if @s1 < @s2, + or a positive value if @s1 > @s2.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="s1" transfer-ownership="none"> + <doc xml:space="preserve">string to compare with @s2</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="s2" transfer-ownership="none"> + <doc xml:space="preserve">string to compare with @s1</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="ascii_strdown" c:identifier="g_ascii_strdown"> + <doc xml:space="preserve">Converts all upper case ASCII letters to lower case ASCII letters.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.)</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">length of @str in bytes, or -1 if @str is nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function name="ascii_string_to_signed" c:identifier="g_ascii_string_to_signed" version="2.54" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @str was a number, otherwise %FALSE.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="base" transfer-ownership="none"> + <doc xml:space="preserve">base of a parsed number</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="min" transfer-ownership="none"> + <doc xml:space="preserve">a lower bound (inclusive)</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="max" transfer-ownership="none"> + <doc xml:space="preserve">an upper bound (inclusive)</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="out_num" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a return location for a number</doc> + <type name="gint64" c:type="gint64*"/> + </parameter> + </parameters> + </function> + <function name="ascii_string_to_unsigned" c:identifier="g_ascii_string_to_unsigned" version="2.54" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @str was a number, otherwise %FALSE.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="base" transfer-ownership="none"> + <doc xml:space="preserve">base of a parsed number</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="min" transfer-ownership="none"> + <doc xml:space="preserve">a lower bound (inclusive)</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="max" transfer-ownership="none"> + <doc xml:space="preserve">an upper bound (inclusive)</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="out_num" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a return location for a number</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + </parameters> + </function> + <function name="ascii_strncasecmp" c:identifier="g_ascii_strncasecmp"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">0 if the strings match, a negative value if @s1 < @s2, + or a positive value if @s1 > @s2.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="s1" transfer-ownership="none"> + <doc xml:space="preserve">string to compare with @s2</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="s2" transfer-ownership="none"> + <doc xml:space="preserve">string to compare with @s1</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">number of characters to compare</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="ascii_strtod" c:identifier="g_ascii_strtod"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #gdouble value.</doc> + <type name="gdouble" c:type="gdouble"/> + </return-value> + <parameters> + <parameter name="nptr" transfer-ownership="none"> + <doc xml:space="preserve">the string to convert to a numeric value.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="endptr" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">if non-%NULL, it returns the + character after the last character used in the conversion.</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </function> + <function name="ascii_strtoll" c:identifier="g_ascii_strtoll" version="2.12"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #gint64 value or zero on error.</doc> + <type name="gint64" c:type="gint64"/> + </return-value> + <parameters> + <parameter name="nptr" transfer-ownership="none"> + <doc xml:space="preserve">the string to convert to a numeric value.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="endptr" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">if non-%NULL, it returns the + character after the last character used in the conversion.</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="base" transfer-ownership="none"> + <doc xml:space="preserve">to be used for the conversion, 2..36 or 0</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="ascii_strtoull" c:identifier="g_ascii_strtoull" version="2.2"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #guint64 value or zero on error.</doc> + <type name="guint64" c:type="guint64"/> + </return-value> + <parameters> + <parameter name="nptr" transfer-ownership="none"> + <doc xml:space="preserve">the string to convert to a numeric value.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="endptr" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">if non-%NULL, it returns the + character after the last character used in the conversion.</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="base" transfer-ownership="none"> + <doc xml:space="preserve">to be used for the conversion, 2..36 or 0</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="ascii_strup" c:identifier="g_ascii_strup"> + <doc xml:space="preserve">Converts all lower case ASCII letters to upper case ASCII letters.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.)</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">length of @str in bytes, or -1 if @str is nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function name="ascii_tolower" c:identifier="g_ascii_tolower"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the result of converting @c to lower case. If @c is + not an ASCII upper case letter, @c is returned unchanged.</doc> + <type name="gchar" c:type="gchar"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">any character</doc> + <type name="gchar" c:type="gchar"/> + </parameter> + </parameters> + </function> + <function name="ascii_toupper" c:identifier="g_ascii_toupper"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the result of converting @c to upper case. If @c is not + an ASCII lower case letter, @c is returned unchanged.</doc> + <type name="gchar" c:type="gchar"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">any character</doc> + <type name="gchar" c:type="gchar"/> + </parameter> + </parameters> + </function> + <function name="ascii_xdigit_value" c:identifier="g_ascii_xdigit_value"> + <doc xml:space="preserve">Determines the numeric value of a character as a hexadecimal +digit. Differs from g_unichar_xdigit_value() because it takes +a char, so there's no worry about sign extension if characters +are signed.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">If @c is a hex digit (according to g_ascii_isxdigit()), + its numeric value. Otherwise, -1.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">an ASCII character.</doc> + <type name="gchar" c:type="gchar"/> + </parameter> + </parameters> + </function> + <function-macro name="assert" c:identifier="g_assert" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="expr"> + <doc xml:space="preserve">the expression to check</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="assert_cmpfloat" c:identifier="g_assert_cmpfloat" version="2.16" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="n1"> + <doc xml:space="preserve">a floating point number</doc> + </parameter> + <parameter name="cmp"> + <doc xml:space="preserve">The comparison operator to use. + One of `==`, `!=`, `<`, `>`, `<=`, `>=`.</doc> + </parameter> + <parameter name="n2"> + <doc xml:space="preserve">another floating point number</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="assert_cmpfloat_with_epsilon" c:identifier="g_assert_cmpfloat_with_epsilon" version="2.58" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="n1"> + <doc xml:space="preserve">a floating point number</doc> + </parameter> + <parameter name="n2"> + <doc xml:space="preserve">another floating point number</doc> + </parameter> + <parameter name="epsilon"> + <doc xml:space="preserve">a numeric value that expresses the expected tolerance + between @n1 and @n2</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="assert_cmphex" c:identifier="g_assert_cmphex" version="2.16" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="n1"> + <doc xml:space="preserve">an unsigned integer</doc> + </parameter> + <parameter name="cmp"> + <doc xml:space="preserve">The comparison operator to use. + One of `==`, `!=`, `<`, `>`, `<=`, `>=`.</doc> + </parameter> + <parameter name="n2"> + <doc xml:space="preserve">another unsigned integer</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="assert_cmpint" c:identifier="g_assert_cmpint" version="2.16" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="n1"> + <doc xml:space="preserve">an integer</doc> + </parameter> + <parameter name="cmp"> + <doc xml:space="preserve">The comparison operator to use. + One of `==`, `!=`, `<`, `>`, `<=`, `>=`.</doc> + </parameter> + <parameter name="n2"> + <doc xml:space="preserve">another integer</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="assert_cmpmem" c:identifier="g_assert_cmpmem" version="2.46" introspectable="0"> + <doc xml:space="preserve">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)); +]|</doc> + <parameters> + <parameter name="m1"> + <doc xml:space="preserve">pointer to a buffer</doc> + </parameter> + <parameter name="l1"> + <doc xml:space="preserve">length of @m1</doc> + </parameter> + <parameter name="m2"> + <doc xml:space="preserve">pointer to another buffer</doc> + </parameter> + <parameter name="l2"> + <doc xml:space="preserve">length of @m2</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="assert_cmpstr" c:identifier="g_assert_cmpstr" version="2.16" introspectable="0"> + <doc xml:space="preserve">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"); +]|</doc> + <parameters> + <parameter name="s1"> + <doc xml:space="preserve">a string (may be %NULL)</doc> + </parameter> + <parameter name="cmp"> + <doc xml:space="preserve">The comparison operator to use. + One of `==`, `!=`, `<`, `>`, `<=`, `>=`.</doc> + </parameter> + <parameter name="s2"> + <doc xml:space="preserve">another string (may be %NULL)</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="assert_cmpuint" c:identifier="g_assert_cmpuint" version="2.16" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="n1"> + <doc xml:space="preserve">an unsigned integer</doc> + </parameter> + <parameter name="cmp"> + <doc xml:space="preserve">The comparison operator to use. + One of `==`, `!=`, `<`, `>`, `<=`, `>=`.</doc> + </parameter> + <parameter name="n2"> + <doc xml:space="preserve">another unsigned integer</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="assert_cmpvariant" c:identifier="g_assert_cmpvariant" version="2.60" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="v1"> + <doc xml:space="preserve">pointer to a #GVariant</doc> + </parameter> + <parameter name="v2"> + <doc xml:space="preserve">pointer to another #GVariant</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="assert_error" c:identifier="g_assert_error" version="2.20" introspectable="0"> + <doc xml:space="preserve">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)`.</doc> + <parameters> + <parameter name="err"> + <doc xml:space="preserve">a #GError, possibly %NULL</doc> + </parameter> + <parameter name="dom"> + <doc xml:space="preserve">the expected error domain (a #GQuark)</doc> + </parameter> + <parameter name="c"> + <doc xml:space="preserve">the expected error code</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="assert_false" c:identifier="g_assert_false" version="2.38" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <parameters> + <parameter name="expr"> + <doc xml:space="preserve">the expression to check</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="assert_no_errno" c:identifier="g_assert_no_errno" version="2.66" introspectable="0"> + <doc xml:space="preserve">Debugging macro to check that an expression has a non-negative return value, +as used by traditional POSIX functions (such as `rmdir()`) to indicate +success. + +If the assertion fails (i.e. the @expr returns a negative value), an error +message is logged and the testcase is marked as failed. The error message +will contain the value of `errno` and its human-readable message from +g_strerror(). + +This macro will clear the value of `errno` before executing @expr.</doc> + <parameters> + <parameter name="expr"> + <doc xml:space="preserve">the expression to check</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="assert_no_error" c:identifier="g_assert_no_error" version="2.20" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="err"> + <doc xml:space="preserve">a #GError, possibly %NULL</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="assert_nonnull" c:identifier="g_assert_nonnull" version="2.40" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <parameters> + <parameter name="expr"> + <doc xml:space="preserve">the expression to check</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="assert_null" c:identifier="g_assert_null" version="2.38" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <parameters> + <parameter name="expr"> + <doc xml:space="preserve">the expression to check</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="assert_true" c:identifier="g_assert_true" version="2.38" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <parameters> + <parameter name="expr"> + <doc xml:space="preserve">the expression to check</doc> + </parameter> + </parameters> + </function-macro> + <function name="assert_warning" c:identifier="g_assert_warning"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="log_domain" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="file" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="line" transfer-ownership="none"> + <type name="gint" c:type="const int"/> + </parameter> + <parameter name="pretty_function" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="expression" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="assertion_message" c:identifier="g_assertion_message"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="domain" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="file" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="line" transfer-ownership="none"> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="func" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="message" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="assertion_message_cmpnum" c:identifier="g_assertion_message_cmpnum" introspectable="0"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="domain" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="file" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="line" transfer-ownership="none"> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="func" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="expr" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="arg1" transfer-ownership="none"> + <type name="long double" c:type="long double"/> + </parameter> + <parameter name="cmp" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="arg2" transfer-ownership="none"> + <type name="long double" c:type="long double"/> + </parameter> + <parameter name="numtype" transfer-ownership="none"> + <type name="gchar" c:type="char"/> + </parameter> + </parameters> + </function> + <function name="assertion_message_cmpstr" c:identifier="g_assertion_message_cmpstr"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="domain" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="file" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="line" transfer-ownership="none"> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="func" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="expr" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="arg1" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cmp" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="arg2" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="assertion_message_error" c:identifier="g_assertion_message_error"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="domain" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="file" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="line" transfer-ownership="none"> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="func" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="expr" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="error" transfer-ownership="none"> + <type name="Error" c:type="const GError*"/> + </parameter> + <parameter name="error_domain" transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </parameter> + <parameter name="error_code" transfer-ownership="none"> + <type name="gint" c:type="int"/> + </parameter> + </parameters> + </function> + <function name="assertion_message_expr" c:identifier="g_assertion_message_expr" introspectable="0"> + <doc xml:space="preserve">Internal function used to print messages from the public g_assert() and +g_assert_not_reached() macros.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">log domain</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">file containing the assertion</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="line" transfer-ownership="none"> + <doc xml:space="preserve">line number of the assertion</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="func" transfer-ownership="none"> + <doc xml:space="preserve">function containing the assertion</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="expr" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">expression which failed</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <docsection name="async_queues"> + <doc xml:space="preserve">Often you need to communicate between different threads. In general +it's safer not to do this by shared memory, but by explicit message +passing. These messages only make sense asynchronously for +multi-threaded applications though, as a synchronous operation could +as well be done in the same thread. + +Asynchronous queues are an exception from most other GLib data +structures, as they can be used simultaneously from multiple threads +without explicit locking and they bring their own builtin reference +counting. This is because the nature of an asynchronous queue is that +it will always be used by at least 2 concurrent threads. + +For using an asynchronous queue you first have to create one with +g_async_queue_new(). #GAsyncQueue structs are reference counted, +use g_async_queue_ref() and g_async_queue_unref() to manage your +references. + +A thread which wants to send a message to that queue simply calls +g_async_queue_push() to push the message to the queue. + +A thread which is expecting messages from an asynchronous queue +simply calls g_async_queue_pop() for that queue. If no message is +available in the queue at that point, the thread is now put to sleep +until a message arrives. The message will be removed from the queue +and returned. The functions g_async_queue_try_pop() and +g_async_queue_timeout_pop() can be used to only check for the presence +of messages or to only wait a certain time for messages respectively. + +For almost every function there exist two variants, one that locks +the queue and one that doesn't. That way you can hold the queue lock +(acquire it with g_async_queue_lock() and release it with +g_async_queue_unlock()) over multiple queue accessing instructions. +This can be necessary to ensure the integrity of the queue, but should +only be used when really necessary, as it can make your life harder +if used unwisely. Normally you should only use the locking function +variants (those without the _unlocked suffix). + +In many cases, it may be more convenient to use #GThreadPool when +you need to distribute work to a set of worker threads instead of +using #GAsyncQueue manually. #GThreadPool uses a GAsyncQueue +internally.</doc> + </docsection> + <function name="atexit" c:identifier="g_atexit" deprecated="1" deprecated-version="2.32"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">It is best to avoid g_atexit().</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">the function to call on normal program termination.</doc> + <type name="VoidFunc" c:type="GVoidFunc"/> + </parameter> + </parameters> + </function> + <function name="atomic_int_add" c:identifier="g_atomic_int_add" version="2.4"> + <doc xml:space="preserve">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). + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value of @atomic before the add, signed</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gint or #guint</doc> + <type name="gint" c:type="volatile gint*"/> + </parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">the value to add</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="atomic_int_and" c:identifier="g_atomic_int_and" version="2.30"> + <doc xml:space="preserve">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; }`. + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value of @atomic before the operation, unsigned</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gint or #guint</doc> + <type name="guint" c:type="volatile guint*"/> + </parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">the value to 'and'</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="atomic_int_compare_and_exchange" c:identifier="g_atomic_int_compare_and_exchange" version="2.4"> + <doc xml:space="preserve">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. + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the exchange took place</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gint or #guint</doc> + <type name="gint" c:type="volatile gint*"/> + </parameter> + <parameter name="oldval" transfer-ownership="none"> + <doc xml:space="preserve">the value to compare with</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="newval" transfer-ownership="none"> + <doc xml:space="preserve">the value to conditionally replace with</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="atomic_int_dec_and_test" c:identifier="g_atomic_int_dec_and_test" version="2.4"> + <doc xml:space="preserve">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. + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the resultant value is zero</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gint or #guint</doc> + <type name="gint" c:type="volatile gint*"/> + </parameter> + </parameters> + </function> + <function name="atomic_int_exchange_and_add" c:identifier="g_atomic_int_exchange_and_add" version="2.4" deprecated="1" deprecated-version="2.30"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_atomic_int_add() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value of @atomic before the add, signed</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gint</doc> + <type name="gint" c:type="volatile gint*"/> + </parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">the value to add</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="atomic_int_get" c:identifier="g_atomic_int_get" version="2.4"> + <doc xml:space="preserve">Gets the current value of @atomic. + +This call acts as a full compiler and hardware +memory barrier (before the get). + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value of the integer</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gint or #guint</doc> + <type name="gint" c:type="volatile const gint*"/> + </parameter> + </parameters> + </function> + <function name="atomic_int_inc" c:identifier="g_atomic_int_inc" version="2.4"> + <doc xml:space="preserve">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. + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gint or #guint</doc> + <type name="gint" c:type="volatile gint*"/> + </parameter> + </parameters> + </function> + <function name="atomic_int_or" c:identifier="g_atomic_int_or" version="2.30"> + <doc xml:space="preserve">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. + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value of @atomic before the operation, unsigned</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gint or #guint</doc> + <type name="guint" c:type="volatile guint*"/> + </parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">the value to 'or'</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="atomic_int_set" c:identifier="g_atomic_int_set" version="2.4"> + <doc xml:space="preserve">Sets the value of @atomic to @newval. + +This call acts as a full compiler and hardware +memory barrier (after the set). + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gint or #guint</doc> + <type name="gint" c:type="volatile gint*"/> + </parameter> + <parameter name="newval" transfer-ownership="none"> + <doc xml:space="preserve">a new value to store</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="atomic_int_xor" c:identifier="g_atomic_int_xor" version="2.30"> + <doc xml:space="preserve">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. + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value of @atomic before the operation, unsigned</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gint or #guint</doc> + <type name="guint" c:type="volatile guint*"/> + </parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">the value to 'xor'</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <docsection name="atomic_operations"> + <doc xml:space="preserve">The following is a collection of compiler macros to provide atomic +access to integer and pointer-sized values. + +The macros that have 'int' in the name will operate on pointers to +#gint and #guint. The macros with 'pointer' in the name will operate +on pointers to any pointer-sized value, including #gsize. There is +no support for 64bit operations on platforms with 32bit pointers +because it is not generally possible to perform these operations +atomically. + +The get, set and exchange operations for integers and pointers +nominally operate on #gint and #gpointer, respectively. Of the +arithmetic operations, the 'add' operation operates on (and returns) +signed integer values (#gint and #gssize) and the 'and', 'or', and +'xor' operations operate on (and return) unsigned integer values +(#guint and #gsize). + +All of the operations act as a full compiler and (where appropriate) +hardware memory barrier. Acquire and release or producer and +consumer barrier semantics are not available through this API. + +It is very important that all accesses to a particular integer or +pointer be performed using only this API and that different sizes of +operation are not mixed or used on overlapping memory regions. Never +read or assign directly from or to a value -- always use this API. + +For simple reference counting purposes you should use +g_atomic_int_inc() and g_atomic_int_dec_and_test(). Other uses that +fall outside of simple reference counting patterns are prone to +subtle bugs and occasionally undefined behaviour. It is also worth +noting that since all of these operations require global +synchronisation of the entire machine, they can be quite slow. In +the case of performing multiple atomic operations it can often be +faster to simply acquire a mutex lock around the critical area, +perform the operations normally and then release the lock.</doc> + </docsection> + <function name="atomic_pointer_add" c:identifier="g_atomic_pointer_add" version="2.30"> + <doc xml:space="preserve">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. + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value of @atomic before the add, signed</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gpointer-sized value</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">the value to add</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function name="atomic_pointer_and" c:identifier="g_atomic_pointer_and" version="2.30"> + <doc xml:space="preserve">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. + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value of @atomic before the operation, unsigned</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gpointer-sized value</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">the value to 'and'</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="atomic_pointer_compare_and_exchange" c:identifier="g_atomic_pointer_compare_and_exchange" version="2.4"> + <doc xml:space="preserve">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. + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the exchange took place</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gpointer-sized value</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + <parameter name="oldval" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the value to compare with</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="newval" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the value to conditionally replace with</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="atomic_pointer_get" c:identifier="g_atomic_pointer_get" version="2.4"> + <doc xml:space="preserve">Gets the current value of @atomic. + +This call acts as a full compiler and hardware +memory barrier (before the get). + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the value of the pointer</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gpointer-sized value</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + </parameters> + </function> + <function name="atomic_pointer_or" c:identifier="g_atomic_pointer_or" version="2.30"> + <doc xml:space="preserve">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. + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value of @atomic before the operation, unsigned</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gpointer-sized value</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">the value to 'or'</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="atomic_pointer_set" c:identifier="g_atomic_pointer_set" version="2.4"> + <doc xml:space="preserve">Sets the value of @atomic to @newval. + +This call acts as a full compiler and hardware +memory barrier (after the set). + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gpointer-sized value</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + <parameter name="newval" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a new value to store</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="atomic_pointer_xor" c:identifier="g_atomic_pointer_xor" version="2.30"> + <doc xml:space="preserve">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. + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value of @atomic before the operation, unsigned</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="atomic" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gpointer-sized value</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">the value to 'xor'</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="atomic_rc_box_acquire" c:identifier="g_atomic_rc_box_acquire" version="2.58"> + <doc xml:space="preserve">Atomically acquires a reference on the data pointed by @mem_block.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to the data, + with its reference count increased</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="mem_block" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to reference counted data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="atomic_rc_box_alloc" c:identifier="g_atomic_rc_box_alloc" version="2.58"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to the allocated memory</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="block_size" transfer-ownership="none"> + <doc xml:space="preserve">the size of the allocation, must be greater than 0</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="atomic_rc_box_alloc0" c:identifier="g_atomic_rc_box_alloc0" version="2.58"> + <doc xml:space="preserve">Allocates @block_size bytes of memory, and adds atomic +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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to the allocated memory</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="block_size" transfer-ownership="none"> + <doc xml:space="preserve">the size of the allocation, must be greater than 0</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="atomic_rc_box_dup" c:identifier="g_atomic_rc_box_dup" version="2.58"> + <doc xml:space="preserve">Allocates a new block of data with atomic reference counting +semantics, and copies @block_size bytes of @mem_block +into it.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to the allocated + memory</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="block_size" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to copy, must be greater than 0</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="mem_block" transfer-ownership="none"> + <doc xml:space="preserve">the memory to copy</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="atomic_rc_box_get_size" c:identifier="g_atomic_rc_box_get_size" version="2.58"> + <doc xml:space="preserve">Retrieves the size of the reference counted data pointed by @mem_block.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the size of the data, in bytes</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="mem_block" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to reference counted data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function-macro name="atomic_rc_box_new" c:identifier="g_atomic_rc_box_new" version="2.58" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">the type to allocate, typically a structure name</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="atomic_rc_box_new0" c:identifier="g_atomic_rc_box_new0" version="2.58" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">the type to allocate, typically a structure name</doc> + </parameter> + </parameters> + </function-macro> + <function name="atomic_rc_box_release" c:identifier="g_atomic_rc_box_release" version="2.58"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mem_block" transfer-ownership="full"> + <doc xml:space="preserve">a pointer to reference counted data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="atomic_rc_box_release_full" c:identifier="g_atomic_rc_box_release_full" version="2.58"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mem_block" transfer-ownership="full"> + <doc xml:space="preserve">a pointer to reference counted data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="clear_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">a function to call when clearing the data</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="atomic_ref_count_compare" c:identifier="g_atomic_ref_count_compare" version="2.58"> + <doc xml:space="preserve">Atomically compares the current value of @arc with @val.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the reference count is the same + as the given value</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="arc" transfer-ownership="none"> + <doc xml:space="preserve">the address of an atomic reference count variable</doc> + <type name="gint" c:type="gatomicrefcount*"/> + </parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">the value to compare</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="atomic_ref_count_dec" c:identifier="g_atomic_ref_count_dec" version="2.58"> + <doc xml:space="preserve">Atomically decreases the reference count.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the reference count reached 0, and %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="arc" transfer-ownership="none"> + <doc xml:space="preserve">the address of an atomic reference count variable</doc> + <type name="gint" c:type="gatomicrefcount*"/> + </parameter> + </parameters> + </function> + <function name="atomic_ref_count_inc" c:identifier="g_atomic_ref_count_inc" version="2.58"> + <doc xml:space="preserve">Atomically increases the reference count.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="arc" transfer-ownership="none"> + <doc xml:space="preserve">the address of an atomic reference count variable</doc> + <type name="gint" c:type="gatomicrefcount*"/> + </parameter> + </parameters> + </function> + <function name="atomic_ref_count_init" c:identifier="g_atomic_ref_count_init" version="2.58"> + <doc xml:space="preserve">Initializes a reference count variable.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="arc" transfer-ownership="none"> + <doc xml:space="preserve">the address of an atomic reference count variable</doc> + <type name="gint" c:type="gatomicrefcount*"/> + </parameter> + </parameters> + </function> + <docsection name="base64"> + <doc xml:space="preserve">Base64 is an encoding that allows a sequence of arbitrary bytes to be +encoded as a sequence of printable ASCII characters. For the definition +of Base64, see +[RFC 1421](http://www.ietf.org/rfc/rfc1421.txt) +or +[RFC 2045](http://www.ietf.org/rfc/rfc2045.txt). +Base64 is most commonly used as a MIME transfer encoding +for email. + +GLib supports incremental encoding using g_base64_encode_step() and +g_base64_encode_close(). Incremental decoding can be done with +g_base64_decode_step(). To encode or decode data in one go, use +g_base64_encode() or g_base64_decode(). To avoid memory allocation when +decoding, you can use g_base64_decode_inplace(). + +Support for Base64 encoding has been added in GLib 2.12.</doc> + </docsection> + <function name="base64_decode" c:identifier="g_base64_decode" version="2.12"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + newly allocated buffer containing the binary data + that @text represents. The returned buffer must + be freed with g_free().</doc> + <array length="1" zero-terminated="0" c:type="guchar*"> + <type name="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="text" transfer-ownership="none"> + <doc xml:space="preserve">zero-terminated string with base64 text to decode</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="out_len" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">The length of the decoded data is written here</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </function> + <function name="base64_decode_inplace" c:identifier="g_base64_decode_inplace" version="2.20"> + <doc xml:space="preserve">Decode a sequence of Base-64 encoded text into binary data +by overwriting the input data.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The binary data that @text responds. This pointer + is the same as the input @text.</doc> + <type name="guint8" c:type="guchar*"/> + </return-value> + <parameters> + <parameter name="text" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">zero-terminated + string with base64 text to decode</doc> + <array length="1" zero-terminated="0" c:type="gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="out_len" direction="inout" caller-allocates="0" transfer-ownership="none"> + <doc xml:space="preserve">The length of the decoded data is written here</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </function> + <function name="base64_decode_step" c:identifier="g_base64_decode_step" version="2.12" introspectable="0"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The number of bytes of output that was written</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="in" transfer-ownership="none"> + <doc xml:space="preserve">binary input data</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">max length of @in data to decode</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="out" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve">output buffer</doc> + <array zero-terminated="0" c:type="guchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="state" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">Saved state between steps, initialize to 0</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="save" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">Saved state between steps, initialize to 0</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </function> + <function name="base64_encode" c:identifier="g_base64_encode" version="2.12"> + <doc xml:space="preserve">Encode a sequence of binary data into its Base-64 stringified +representation.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated, zero-terminated Base-64 + encoded string representing @data. The returned string must + be freed with g_free().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the binary data to encode</doc> + <array length="1" zero-terminated="0" c:type="const guchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the length of @data</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="base64_encode_close" c:identifier="g_base64_encode_close" version="2.12"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The number of bytes of output that was written</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="break_lines" transfer-ownership="none"> + <doc xml:space="preserve">whether to break long lines</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="out" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">pointer to destination buffer</doc> + <array zero-terminated="0" c:type="gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="state" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">Saved state from g_base64_encode_step()</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="save" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">Saved state from g_base64_encode_step()</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </function> + <function name="base64_encode_step" c:identifier="g_base64_encode_step" version="2.12"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The number of bytes of output that was written</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="in" transfer-ownership="none"> + <doc xml:space="preserve">the binary data to encode</doc> + <array length="1" zero-terminated="0" c:type="const guchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the length of @in</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="break_lines" transfer-ownership="none"> + <doc xml:space="preserve">whether to break long lines</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="out" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">pointer to destination buffer</doc> + <array zero-terminated="0" c:type="gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="state" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">Saved state between steps, initialize to 0</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="save" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">Saved state between steps, initialize to 0</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </function> + <function name="basename" c:identifier="g_basename" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">Gets the name of the file without any leading directory +components. It returns a pointer into the given file name +string.</doc> + <doc-deprecated xml:space="preserve">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.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the name of the file without any leading + directory components</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="file_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the file</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="bit_lock" c:identifier="g_bit_lock" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to an integer</doc> + <type name="gint" c:type="volatile gint*"/> + </parameter> + <parameter name="lock_bit" transfer-ownership="none"> + <doc xml:space="preserve">a bit value between 0 and 31</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="bit_nth_lsf" c:identifier="g_bit_nth_lsf"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the index of the first bit set which is higher than @nth_bit, or -1 + if no higher bits are set</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="mask" transfer-ownership="none"> + <doc xml:space="preserve">a #gulong containing flags</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + <parameter name="nth_bit" transfer-ownership="none"> + <doc xml:space="preserve">the index of the bit to start the search from</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="bit_nth_msf" c:identifier="g_bit_nth_msf"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the index of the first bit set which is lower than @nth_bit, or -1 + if no lower bits are set</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="mask" transfer-ownership="none"> + <doc xml:space="preserve">a #gulong containing flags</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + <parameter name="nth_bit" transfer-ownership="none"> + <doc xml:space="preserve">the index of the bit to start the search from</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="bit_storage" c:identifier="g_bit_storage"> + <doc xml:space="preserve">Gets the number of bits used to hold @number, +e.g. if @number is 4, 3 bits are needed.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bits used to hold @number</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="number" transfer-ownership="none"> + <doc xml:space="preserve">a #guint</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + </parameters> + </function> + <function name="bit_trylock" c:identifier="g_bit_trylock" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the lock was acquired</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to an integer</doc> + <type name="gint" c:type="volatile gint*"/> + </parameter> + <parameter name="lock_bit" transfer-ownership="none"> + <doc xml:space="preserve">a bit value between 0 and 31</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="bit_unlock" c:identifier="g_bit_unlock" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to an integer</doc> + <type name="gint" c:type="volatile gint*"/> + </parameter> + <parameter name="lock_bit" transfer-ownership="none"> + <doc xml:space="preserve">a bit value between 0 and 31</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="bookmark_file_error_quark" c:identifier="g_bookmark_file_error_quark" moved-to="BookmarkFile.error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <docsection name="bookmarkfile"> + <doc xml:space="preserve">GBookmarkFile lets you parse, edit or create files containing bookmarks +to URI, along with some meta-data about the resource pointed by the URI +like its MIME type, the application that is registering the bookmark and +the icon that should be used to represent the bookmark. The data is stored +using the +[Desktop Bookmark Specification](http://www.gnome.org/~ebassi/bookmark-spec). + +The syntax of the bookmark files is described in detail inside the +Desktop Bookmark Specification, here is a quick summary: bookmark +files use a sub-class of the XML Bookmark Exchange Language +specification, consisting of valid UTF-8 encoded XML, under the +<xbel> root element; each bookmark is stored inside a +<bookmark> element, using its URI: no relative paths can +be used inside a bookmark file. The bookmark may have a user defined +title and description, to be used instead of the URI. Under the +<metadata> element, with its owner attribute set to +`http://freedesktop.org`, is stored the meta-data about a resource +pointed by its URI. The meta-data consists of the resource's MIME +type; the applications that have registered a bookmark; the groups +to which a bookmark belongs to; a visibility flag, used to set the +bookmark as "private" to the applications and groups that has it +registered; the URI and MIME type of an icon, to be used when +displaying the bookmark inside a GUI. + +Here is an example of a bookmark file: +[bookmarks.xbel](https://git.gnome.org/browse/glib/tree/glib/tests/bookmarks.xbel) + +A bookmark file might contain more than one bookmark; each bookmark +is accessed through its URI. + +The important caveat of bookmark files is that when you add a new +bookmark you must also add the application that is registering it, using +g_bookmark_file_add_application() or g_bookmark_file_set_application_info(). +If a bookmark has no applications then it won't be dumped when creating +the on disk representation, using g_bookmark_file_to_data() or +g_bookmark_file_to_file(). + +The #GBookmarkFile parser was added in GLib 2.12.</doc> + </docsection> + <function name="build_filename" c:identifier="g_build_filename" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated string that must be freed with + g_free().</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="first_element" transfer-ownership="none"> + <doc xml:space="preserve">the first element in the path</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">remaining elements in path, terminated by %NULL</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="build_filename_valist" c:identifier="g_build_filename_valist" version="2.56" introspectable="0"> + <doc xml:space="preserve">Behaves exactly like g_build_filename(), but takes the path elements +as a va_list. This function is mainly meant for language bindings.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated string that must be freed + with g_free().</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="first_element" transfer-ownership="none"> + <doc xml:space="preserve">the first element in the path</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of remaining elements in path</doc> + <type name="va_list" c:type="va_list*"/> + </parameter> + </parameters> + </function> + <function name="build_filenamev" c:identifier="g_build_filenamev" version="2.8"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated string that must be freed + with g_free().</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">%NULL-terminated + array of strings containing the path elements.</doc> + <array c:type="gchar**"> + <type name="filename"/> + </array> + </parameter> + </parameters> + </function> + <function name="build_path" c:identifier="g_build_path" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated string that must be freed with + g_free().</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="separator" transfer-ownership="none"> + <doc xml:space="preserve">a string used to separator the elements of the path.</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="first_element" transfer-ownership="none"> + <doc xml:space="preserve">the first element in the path</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">remaining elements in path, terminated by %NULL</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="build_pathv" c:identifier="g_build_pathv" version="2.8"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated string that must be freed + with g_free().</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="separator" transfer-ownership="none"> + <doc xml:space="preserve">a string used to separator the elements of the path.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">%NULL-terminated + array of strings containing the path elements.</doc> + <array c:type="gchar**"> + <type name="filename"/> + </array> + </parameter> + </parameters> + </function> + <function name="byte_array_free" c:identifier="g_byte_array_free" moved-to="ByteArray.free"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the element data if @free_segment is %FALSE, otherwise + %NULL. The element data should be freed using g_free().</doc> + <type name="guint8" c:type="guint8*"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="free_segment" transfer-ownership="none"> + <doc xml:space="preserve">if %TRUE the actual byte data is freed as well</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="byte_array_free_to_bytes" c:identifier="g_byte_array_free_to_bytes" moved-to="ByteArray.free_to_bytes" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new immutable #GBytes representing same + byte data that was in the array</doc> + <type name="Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="full"> + <doc xml:space="preserve">a #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + </parameters> + </function> + <function name="byte_array_new" c:identifier="g_byte_array_new" moved-to="ByteArray.new"> + <doc xml:space="preserve">Creates a new #GByteArray with a reference count of 1.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </return-value> + </function> + <function name="byte_array_new_take" c:identifier="g_byte_array_new_take" moved-to="ByteArray.new_take" version="2.32"> + <doc xml:space="preserve">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(). + +Do not use it if @len is greater than %G_MAXUINT. #GByteArray +stores the length of its data in #guint, which may be shorter than +#gsize.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="full"> + <doc xml:space="preserve">byte data for the array</doc> + <array length="1" zero-terminated="0" c:type="guint8*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">length of @data</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="byte_array_steal" c:identifier="g_byte_array_steal" moved-to="ByteArray.steal" version="2.64"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the element data, which should be + freed using g_free().</doc> + <type name="guint8" c:type="guint8*"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray.</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="len" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">pointer to retrieve the number of + elements of the original array</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </function> + <function name="byte_array_unref" c:identifier="g_byte_array_unref" moved-to="ByteArray.unref" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="array" transfer-ownership="none"> + <doc xml:space="preserve">A #GByteArray</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + </parameters> + </function> + <docsection name="byte_order"> + <doc xml:space="preserve">These macros provide a portable way to determine the host byte order +and to convert values between different byte orders. + +The byte order is the order in which bytes are stored to create larger +data types such as the #gint and #glong values. +The host byte order is the byte order used on the current machine. + +Some processors store the most significant bytes (i.e. the bytes that +hold the largest part of the value) first. These are known as big-endian +processors. Other processors (notably the x86 family) store the most +significant byte last. These are known as little-endian processors. + +Finally, to complicate matters, some other processors store the bytes in +a rather curious order known as PDP-endian. For a 4-byte word, the 3rd +most significant byte is stored first, then the 4th, then the 1st and +finally the 2nd. + +Obviously there is a problem when these different processors communicate +with each other, for example over networks or by using binary file formats. +This is where these macros come in. They are typically used to convert +values into a byte order which has been agreed on for use when +communicating between different processors. The Internet uses what is +known as 'network byte order' as the standard byte order (which is in +fact the big-endian byte order). + +Note that the byte order conversion macros may evaluate their arguments +multiple times, thus you should not use them with arguments which have +side-effects.</doc> + </docsection> + <function name="canonicalize_filename" c:identifier="g_canonicalize_filename" version="2.58"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string with the +canonical file path</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">the name of the file</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="relative_to" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the relative directory, or %NULL +to use the current working directory</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="chdir" c:identifier="g_chdir" version="2.8"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">0 on success, -1 if an error occurred.</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">a pathname in the GLib file name encoding + (UTF-8 on Windows)</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="check_version" c:identifier="glib_check_version" version="2.6"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%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.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="required_major" transfer-ownership="none"> + <doc xml:space="preserve">the required major version</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="required_minor" transfer-ownership="none"> + <doc xml:space="preserve">the required minor version</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="required_micro" transfer-ownership="none"> + <doc xml:space="preserve">the required micro version</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <docsection name="checkedmath"> + <doc xml:space="preserve">GLib offers a set of macros for doing additions and multiplications +of unsigned integers, with checks for overflows. + +The helpers all have three arguments. A pointer to the destination +is always the first argument and the operands to the operation are +the other two. + +Following standard GLib convention, the helpers return %TRUE in case +of success (ie: no overflow). + +The helpers may be macros, normal functions or inlines. They may be +implemented with inline assembly or compiler intrinsics where +available.</doc> + </docsection> + <docsection name="checksum"> + <doc xml:space="preserve">GLib provides a generic API for computing checksums (or "digests") +for a sequence of arbitrary bytes, using various hashing algorithms +like MD5, SHA-1 and SHA-256. Checksums are commonly used in various +environments and specifications. + +GLib supports incremental checksums using the GChecksum data +structure, by calling g_checksum_update() as long as there's data +available and then using g_checksum_get_string() or +g_checksum_get_digest() to compute the checksum and return it either +as a string in hexadecimal form, or as a raw sequence of bytes. To +compute the checksum for binary blobs and NUL-terminated strings in +one go, use the convenience functions g_compute_checksum_for_data() +and g_compute_checksum_for_string(), respectively. + +Support for checksums has been added in GLib 2.16</doc> + </docsection> + <function name="checksum_type_get_length" c:identifier="g_checksum_type_get_length" moved-to="Checksum.type_get_length" version="2.16"> + <doc xml:space="preserve">Gets the length in bytes of digests of type @checksum_type</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the checksum length, or -1 if @checksum_type is +not supported.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="checksum_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GChecksumType</doc> + <type name="ChecksumType" c:type="GChecksumType"/> + </parameter> + </parameters> + </function> + <function name="child_watch_add" c:identifier="g_child_watch_add" shadowed-by="child_watch_add_full" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ID (greater than 0) of the event source.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="pid" transfer-ownership="none"> + <doc xml:space="preserve">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).</doc> + <type name="Pid" c:type="GPid"/> + </parameter> + <parameter name="function" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">function to call</doc> + <type name="ChildWatchFunc" c:type="GChildWatchFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="child_watch_add_full" c:identifier="g_child_watch_add_full" shadows="child_watch_add" version="2.4"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ID (greater than 0) of the event source.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="priority" transfer-ownership="none"> + <doc xml:space="preserve">the priority of the idle source. Typically this will be in the + range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="pid" transfer-ownership="none"> + <doc xml:space="preserve">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).</doc> + <type name="Pid" c:type="GPid"/> + </parameter> + <parameter name="function" transfer-ownership="none" scope="notified" closure="3" destroy="4"> + <doc xml:space="preserve">function to call</doc> + <type name="ChildWatchFunc" c:type="GChildWatchFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">function to call when the idle is removed, or %NULL</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="child_watch_source_new" c:identifier="g_child_watch_source_new" version="2.4"> + <doc xml:space="preserve">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 `SIGCHLD` + +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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the newly-created child watch source</doc> + <type name="Source" c:type="GSource*"/> + </return-value> + <parameters> + <parameter name="pid" transfer-ownership="none"> + <doc xml:space="preserve">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).</doc> + <type name="Pid" c:type="GPid"/> + </parameter> + </parameters> + </function> + <function name="clear_error" c:identifier="g_clear_error" throws="1"> + <doc xml:space="preserve">If @err or *@err is %NULL, does nothing. Otherwise, +calls g_error_free() on *@err and sets *@err to %NULL.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </function> + <function name="clear_handle_id" c:identifier="g_clear_handle_id" version="2.56" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="tag_ptr" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to the handler ID</doc> + <type name="guint" c:type="guint*"/> + </parameter> + <parameter name="clear_func" transfer-ownership="none"> + <doc xml:space="preserve">the function to call to clear the handler</doc> + <type name="ClearHandleFunc" c:type="GClearHandleFunc"/> + </parameter> + </parameters> + </function> + <function name="clear_list" c:identifier="g_clear_list" version="2.64" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="list_ptr" transfer-ownership="none"> + <doc xml:space="preserve">a #GList return location</doc> + <type name="GLib.List" c:type="GList**"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">the function to pass to g_list_free_full() or %NULL to not free elements</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="clear_pointer" c:identifier="g_clear_pointer" version="2.34" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="pp" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a variable, struct member etc. holding a + pointer</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + <parameter name="destroy" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">a function to which a gpointer can be passed, to destroy *@pp</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="clear_slist" c:identifier="g_clear_slist" version="2.64" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="slist_ptr" transfer-ownership="none"> + <doc xml:space="preserve">a #GSList return location</doc> + <type name="GLib.SList" c:type="GSList**"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">the function to pass to g_slist_free_full() or %NULL to not free elements</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="close" c:identifier="g_close" version="2.36" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if there was an error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">A file descriptor</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="compute_checksum_for_bytes" c:identifier="g_compute_checksum_for_bytes" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the digest of the binary data as a + string in hexadecimal, or %NULL if g_checksum_new() fails for + @checksum_type. The returned string should be freed with g_free() when + done using it.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="checksum_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GChecksumType</doc> + <type name="ChecksumType" c:type="GChecksumType"/> + </parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">binary blob to compute the digest of</doc> + <type name="Bytes" c:type="GBytes*"/> + </parameter> + </parameters> + </function> + <function name="compute_checksum_for_data" c:identifier="g_compute_checksum_for_data" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the digest of the binary data as a + string in hexadecimal, or %NULL if g_checksum_new() fails for + @checksum_type. The returned string should be freed with g_free() when + done using it.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="checksum_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GChecksumType</doc> + <type name="ChecksumType" c:type="GChecksumType"/> + </parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">binary blob to compute the digest of</doc> + <array length="2" zero-terminated="0" c:type="const guchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">length of @data</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="compute_checksum_for_string" c:identifier="g_compute_checksum_for_string" version="2.16"> + <doc xml:space="preserve">Computes the checksum of a string. + +The hexadecimal string returned will be in lower case.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the checksum as a hexadecimal string, + or %NULL if g_checksum_new() fails for @checksum_type. The returned string + should be freed with g_free() when done using it.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="checksum_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GChecksumType</doc> + <type name="ChecksumType" c:type="GChecksumType"/> + </parameter> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">the string to compute the checksum of</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of the string, or -1 if the string is null-terminated.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function name="compute_hmac_for_bytes" c:identifier="g_compute_hmac_for_bytes" version="2.50"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the HMAC of the binary data as a string in hexadecimal. + The returned string should be freed with g_free() when done using it.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="digest_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GChecksumType to use for the HMAC</doc> + <type name="ChecksumType" c:type="GChecksumType"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to use in the HMAC</doc> + <type name="Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">binary blob to compute the HMAC of</doc> + <type name="Bytes" c:type="GBytes*"/> + </parameter> + </parameters> + </function> + <function name="compute_hmac_for_data" c:identifier="g_compute_hmac_for_data" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the HMAC of the binary data as a string in hexadecimal. + The returned string should be freed with g_free() when done using it.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="digest_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GChecksumType to use for the HMAC</doc> + <type name="ChecksumType" c:type="GChecksumType"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to use in the HMAC</doc> + <array length="2" zero-terminated="0" c:type="const guchar*"> + <type name="guint8" c:type="guchar"/> + </array> + </parameter> + <parameter name="key_len" transfer-ownership="none"> + <doc xml:space="preserve">the length of the key</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">binary blob to compute the HMAC of</doc> + <array length="4" zero-terminated="0" c:type="const guchar*"> + <type name="guint8" c:type="guchar"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">length of @data</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="compute_hmac_for_string" c:identifier="g_compute_hmac_for_string" version="2.30"> + <doc xml:space="preserve">Computes the HMAC for a string. + +The hexadecimal string returned will be in lower case.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the HMAC as a hexadecimal string. + The returned string should be freed with g_free() + when done using it.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="digest_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GChecksumType to use for the HMAC</doc> + <type name="ChecksumType" c:type="GChecksumType"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to use in the HMAC</doc> + <array length="2" zero-terminated="0" c:type="const guchar*"> + <type name="guint8" c:type="guchar"/> + </array> + </parameter> + <parameter name="key_len" transfer-ownership="none"> + <doc xml:space="preserve">the length of the key</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">the string to compute the HMAC for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of the string, or -1 if the string is nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <docsection name="conversions"> + <doc xml:space="preserve">The g_convert() family of function wraps the functionality of iconv(). +In addition to pure character set conversions, GLib has functions to +deal with the extra complications of encodings for file names. + +## File Name Encodings + +Historically, UNIX has not had a defined encoding for file names: +a file name is valid as long as it does not have path separators +in it ("/"). However, displaying file names may require conversion: +from the character set in which they were created, to the character +set in which the application operates. Consider the Spanish file name +"Presentación.sxi". If the application which created it uses +ISO-8859-1 for its encoding, +|[ +Character: P r e s e n t a c i ó n . s x i +Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69 +]| +However, if the application use UTF-8, the actual file name on +disk would look like this: +|[ +Character: P r e s e n t a c i ó n . s x i +Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69 +]| +Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use +GLib do the same thing. If you get a file name from the file system, +for example, from readdir() or from g_dir_read_name(), and you wish +to display the file name to the user, you will need to convert it +into UTF-8. The opposite case is when the user types the name of a +file they wish to save: the toolkit will give you that string in +UTF-8 encoding, and you will need to convert it to the character +set used for file names before you can create the file with open() +or fopen(). + +By default, GLib assumes that file names on disk are in UTF-8 +encoding. This is a valid assumption for file systems which +were created relatively recently: most applications use UTF-8 +encoding for their strings, and that is also what they use for +the file names they create. However, older file systems may +still contain file names created in "older" encodings, such as +ISO-8859-1. In this case, for compatibility reasons, you may want +to instruct GLib to use that particular encoding for file names +rather than UTF-8. You can do this by specifying the encoding for +file names in the [`G_FILENAME_ENCODING`][G_FILENAME_ENCODING] +environment variable. For example, if your installation uses +ISO-8859-1 for file names, you can put this in your `~/.profile`: +|[ +export G_FILENAME_ENCODING=ISO-8859-1 +]| +GLib provides the functions g_filename_to_utf8() and +g_filename_from_utf8() to perform the necessary conversions. +These functions convert file names from the encoding specified +in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. This +[diagram][file-name-encodings-diagram] illustrates how +these functions are used to convert between UTF-8 and the +encoding for file names in the file system. + +## Conversion between file name encodings # {#file-name-encodings-diagram) + +![](file-name-encodings.png) + +## Checklist for Application Writers + +This section is a practical summary of the detailed +things to do to make sure your applications process file +name encodings correctly. + +1. If you get a file name from the file system from a function + such as readdir() or gtk_file_chooser_get_filename(), you do + not need to do any conversion to pass that file name to + functions like open(), rename(), or fopen() -- those are "raw" + file names which the file system understands. + +2. If you need to display a file name, convert it to UTF-8 first + by using g_filename_to_utf8(). If conversion fails, display a + string like "Unknown file name". Do not convert this string back + into the encoding used for file names if you wish to pass it to + the file system; use the original file name instead. + + For example, the document window of a word processor could display + "Unknown file name" in its title bar but still let the user save + the file, as it would keep the raw file name internally. This + can happen if the user has not set the `G_FILENAME_ENCODING` + environment variable even though he has files whose names are + not encoded in UTF-8. + +3. If your user interface lets the user type a file name for saving + or renaming, convert it to the encoding used for file names in + the file system by using g_filename_from_utf8(). Pass the converted + file name to functions like fopen(). If conversion fails, ask the + user to enter a different file name. This can happen if the user + types Japanese characters when `G_FILENAME_ENCODING` is set to + `ISO-8859-1`, for example.</doc> + </docsection> + <function name="convert" c:identifier="g_convert" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + 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.</doc> + <array length="5" zero-terminated="0" c:type="gchar*"> + <type name="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve"> + the string to convert.</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">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)</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="to_codeset" transfer-ownership="none"> + <doc xml:space="preserve">name of character set into which to convert @str</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="from_codeset" transfer-ownership="none"> + <doc xml:space="preserve">character set of @str.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">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.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of bytes stored in + the output buffer (not including the terminating nul).</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </function> + <function name="convert_error_quark" c:identifier="g_convert_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="convert_with_fallback" c:identifier="g_convert_with_fallback" throws="1"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + 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.</doc> + <array length="6" zero-terminated="0" c:type="gchar*"> + <type name="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve"> + the string to convert.</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">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)</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="to_codeset" transfer-ownership="none"> + <doc xml:space="preserve">name of character set into which to convert @str</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="from_codeset" transfer-ownership="none"> + <doc xml:space="preserve">character set of @str.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="fallback" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">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.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of bytes stored in + the output buffer (not including the terminating nul).</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </function> + <function name="convert_with_iconv" c:identifier="g_convert_with_iconv" introspectable="0" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + 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.</doc> + <array length="4" zero-terminated="0" c:type="gchar*"> + <type name="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve"> + the string to convert.</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">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)</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="converter" transfer-ownership="none"> + <doc xml:space="preserve">conversion descriptor from g_iconv_open()</doc> + <type name="IConv" c:type="GIConv"/> + </parameter> + <parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">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.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of bytes stored in + the output buffer (not including the terminating nul).</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </function> + <docsection name="datalist"> + <doc xml:space="preserve">Keyed data lists provide lists of arbitrary data elements which can +be accessed either with a string or with a #GQuark corresponding to +the string. + +The #GQuark methods are quicker, since the strings have to be +converted to #GQuarks anyway. + +Data lists are used for associating arbitrary data with #GObjects, +using g_object_set_data() and related functions. + +To create a datalist, use g_datalist_init(). + +To add data elements to a datalist use g_datalist_id_set_data(), +g_datalist_id_set_data_full(), g_datalist_set_data() and +g_datalist_set_data_full(). + +To get data elements from a datalist use g_datalist_id_get_data() +and g_datalist_get_data(). + +To iterate over all data elements in a datalist use +g_datalist_foreach() (not thread-safe). + +To remove data elements from a datalist use +g_datalist_id_remove_data() and g_datalist_remove_data(). + +To remove all data elements from a datalist, use g_datalist_clear().</doc> + </docsection> + <function name="datalist_clear" c:identifier="g_datalist_clear" introspectable="0"> + <doc xml:space="preserve">Frees all the data elements of the datalist. +The data elements' destroy functions are called +if they have been set.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="datalist" transfer-ownership="none"> + <doc xml:space="preserve">a datalist.</doc> + <type name="Data" c:type="GData**"/> + </parameter> + </parameters> + </function> + <function name="datalist_foreach" c:identifier="g_datalist_foreach"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="datalist" transfer-ownership="none"> + <doc xml:space="preserve">a datalist.</doc> + <type name="Data" c:type="GData**"/> + </parameter> + <parameter name="func" transfer-ownership="none" scope="call" closure="2"> + <doc xml:space="preserve">the function to call for each data element.</doc> + <type name="DataForeachFunc" c:type="GDataForeachFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to the function.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="datalist_get_data" c:identifier="g_datalist_get_data"> + <doc xml:space="preserve">Gets a data element, using its string identifier. This is slower than +g_datalist_id_get_data() because it compares strings.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the data element, or %NULL if it + is not found.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="datalist" transfer-ownership="none"> + <doc xml:space="preserve">a datalist.</doc> + <type name="Data" c:type="GData**"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the string identifying a data element.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="datalist_get_flags" c:identifier="g_datalist_get_flags" version="2.8"> + <doc xml:space="preserve">Gets flags values packed in together with the datalist. +See g_datalist_set_flags().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the flags of the datalist</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="datalist" transfer-ownership="none"> + <doc xml:space="preserve">pointer to the location that holds a list</doc> + <type name="Data" c:type="GData**"/> + </parameter> + </parameters> + </function> + <function name="datalist_id_dup_data" c:identifier="g_datalist_id_dup_data" version="2.34" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="datalist" transfer-ownership="none"> + <doc xml:space="preserve">location of a datalist</doc> + <type name="Data" c:type="GData**"/> + </parameter> + <parameter name="key_id" transfer-ownership="none"> + <doc xml:space="preserve">the #GQuark identifying a data element</doc> + <type name="Quark" c:type="GQuark"/> + </parameter> + <parameter name="dup_func" transfer-ownership="none" nullable="1" allow-none="1" scope="call" closure="3"> + <doc xml:space="preserve">function to duplicate the old value</doc> + <type name="DuplicateFunc" c:type="GDuplicateFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">passed as user_data to @dup_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="datalist_id_get_data" c:identifier="g_datalist_id_get_data"> + <doc xml:space="preserve">Retrieves the data element corresponding to @key_id.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the data element, or %NULL if + it is not found.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="datalist" transfer-ownership="none"> + <doc xml:space="preserve">a datalist.</doc> + <type name="Data" c:type="GData**"/> + </parameter> + <parameter name="key_id" transfer-ownership="none"> + <doc xml:space="preserve">the #GQuark identifying a data element.</doc> + <type name="Quark" c:type="GQuark"/> + </parameter> + </parameters> + </function> + <function-macro name="datalist_id_remove_data" c:identifier="g_datalist_id_remove_data" introspectable="0"> + <doc xml:space="preserve">Removes an element, using its #GQuark identifier.</doc> + <parameters> + <parameter name="dl"> + <doc xml:space="preserve">a datalist.</doc> + </parameter> + <parameter name="q"> + <doc xml:space="preserve">the #GQuark identifying the data element.</doc> + </parameter> + </parameters> + </function-macro> + <function name="datalist_id_remove_no_notify" c:identifier="g_datalist_id_remove_no_notify" introspectable="0"> + <doc xml:space="preserve">Removes an element, without calling its destroy notification +function.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the data previously stored at @key_id, + or %NULL if none.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="datalist" transfer-ownership="none"> + <doc xml:space="preserve">a datalist.</doc> + <type name="Data" c:type="GData**"/> + </parameter> + <parameter name="key_id" transfer-ownership="none"> + <doc xml:space="preserve">the #GQuark identifying a data element.</doc> + <type name="Quark" c:type="GQuark"/> + </parameter> + </parameters> + </function> + <function name="datalist_id_replace_data" c:identifier="g_datalist_id_replace_data" version="2.34" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the existing value for @key_id was replaced + by @newval, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="datalist" transfer-ownership="none"> + <doc xml:space="preserve">location of a datalist</doc> + <type name="Data" c:type="GData**"/> + </parameter> + <parameter name="key_id" transfer-ownership="none"> + <doc xml:space="preserve">the #GQuark identifying a data element</doc> + <type name="Quark" c:type="GQuark"/> + </parameter> + <parameter name="oldval" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the old value to compare against</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="newval" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the new value to replace it with</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">destroy notify for the new value</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + <parameter name="old_destroy" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1" scope="async"> + <doc xml:space="preserve">destroy notify for the existing value</doc> + <type name="DestroyNotify" c:type="GDestroyNotify*"/> + </parameter> + </parameters> + </function> + <function-macro name="datalist_id_set_data" c:identifier="g_datalist_id_set_data" introspectable="0"> + <doc xml:space="preserve">Sets the data corresponding to the given #GQuark id. Any previous +data with the same key is removed, and its destroy function is +called.</doc> + <parameters> + <parameter name="dl"> + <doc xml:space="preserve">a datalist.</doc> + </parameter> + <parameter name="q"> + <doc xml:space="preserve">the #GQuark to identify the data element.</doc> + </parameter> + <parameter name="d"> + <doc xml:space="preserve">the data element, or %NULL to remove any previous element + corresponding to @q.</doc> + </parameter> + </parameters> + </function-macro> + <function name="datalist_id_set_data_full" c:identifier="g_datalist_id_set_data_full" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="datalist" transfer-ownership="none"> + <doc xml:space="preserve">a datalist.</doc> + <type name="Data" c:type="GData**"/> + </parameter> + <parameter name="key_id" transfer-ownership="none"> + <doc xml:space="preserve">the #GQuark to identify the data element.</doc> + <type name="Quark" c:type="GQuark"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data element or %NULL to remove any previous element + corresponding to @key_id.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">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.</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="datalist_init" c:identifier="g_datalist_init" introspectable="0"> + <doc xml:space="preserve">Resets the datalist to %NULL. It does not free any memory or call +any destroy functions.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="datalist" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a pointer to a datalist.</doc> + <type name="Data" c:type="GData**"/> + </parameter> + </parameters> + </function> + <function-macro name="datalist_remove_data" c:identifier="g_datalist_remove_data" introspectable="0"> + <doc xml:space="preserve">Removes an element using its string identifier. The data element's +destroy function is called if it has been set.</doc> + <parameters> + <parameter name="dl"> + <doc xml:space="preserve">a datalist.</doc> + </parameter> + <parameter name="k"> + <doc xml:space="preserve">the string identifying the data element.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="datalist_remove_no_notify" c:identifier="g_datalist_remove_no_notify" introspectable="0"> + <doc xml:space="preserve">Removes an element, without calling its destroy notifier.</doc> + <parameters> + <parameter name="dl"> + <doc xml:space="preserve">a datalist.</doc> + </parameter> + <parameter name="k"> + <doc xml:space="preserve">the string identifying the data element.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="datalist_set_data" c:identifier="g_datalist_set_data" introspectable="0"> + <doc xml:space="preserve">Sets the data element corresponding to the given string identifier.</doc> + <parameters> + <parameter name="dl"> + <doc xml:space="preserve">a datalist.</doc> + </parameter> + <parameter name="k"> + <doc xml:space="preserve">the string to identify the data element.</doc> + </parameter> + <parameter name="d"> + <doc xml:space="preserve">the data element, or %NULL to remove any previous element + corresponding to @k.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="datalist_set_data_full" c:identifier="g_datalist_set_data_full" introspectable="0"> + <doc xml:space="preserve">Sets the data element corresponding to the given string identifier, +and the function to be called when the data element is removed.</doc> + <parameters> + <parameter name="dl"> + <doc xml:space="preserve">a datalist.</doc> + </parameter> + <parameter name="k"> + <doc xml:space="preserve">the string to identify the data element.</doc> + </parameter> + <parameter name="d"> + <doc xml:space="preserve">the data element, or %NULL to remove any previous element + corresponding to @k.</doc> + </parameter> + <parameter name="f"> + <doc xml:space="preserve">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.</doc> + </parameter> + </parameters> + </function-macro> + <function name="datalist_set_flags" c:identifier="g_datalist_set_flags" version="2.8"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="datalist" transfer-ownership="none"> + <doc xml:space="preserve">pointer to the location that holds a list</doc> + <type name="Data" c:type="GData**"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="datalist_unset_flags" c:identifier="g_datalist_unset_flags" version="2.8"> + <doc xml:space="preserve">Turns off flag values for a data list. See g_datalist_unset_flags()</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="datalist" transfer-ownership="none"> + <doc xml:space="preserve">pointer to the location that holds a list</doc> + <type name="Data" c:type="GData**"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="dataset_destroy" c:identifier="g_dataset_destroy"> + <doc xml:space="preserve">Destroys the dataset, freeing all memory allocated, and calling any +destroy functions set for data elements.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="dataset_location" transfer-ownership="none"> + <doc xml:space="preserve">the location identifying the dataset.</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="dataset_foreach" c:identifier="g_dataset_foreach"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="dataset_location" transfer-ownership="none"> + <doc xml:space="preserve">the location identifying the dataset.</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="func" transfer-ownership="none" scope="call" closure="2"> + <doc xml:space="preserve">the function to call for each data element.</doc> + <type name="DataForeachFunc" c:type="GDataForeachFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to the function.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function-macro name="dataset_get_data" c:identifier="g_dataset_get_data" introspectable="0"> + <doc xml:space="preserve">Gets the data element corresponding to a string.</doc> + <parameters> + <parameter name="l"> + <doc xml:space="preserve">the location identifying the dataset.</doc> + </parameter> + <parameter name="k"> + <doc xml:space="preserve">the string identifying the data element.</doc> + </parameter> + </parameters> + </function-macro> + <function name="dataset_id_get_data" c:identifier="g_dataset_id_get_data"> + <doc xml:space="preserve">Gets the data element corresponding to a #GQuark.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the data element corresponding to + the #GQuark, or %NULL if it is not found.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="dataset_location" transfer-ownership="none"> + <doc xml:space="preserve">the location identifying the dataset.</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="key_id" transfer-ownership="none"> + <doc xml:space="preserve">the #GQuark id to identify the data element.</doc> + <type name="Quark" c:type="GQuark"/> + </parameter> + </parameters> + </function> + <function-macro name="dataset_id_remove_data" c:identifier="g_dataset_id_remove_data" introspectable="0"> + <doc xml:space="preserve">Removes a data element from a dataset. The data element's destroy +function is called if it has been set.</doc> + <parameters> + <parameter name="l"> + <doc xml:space="preserve">the location identifying the dataset.</doc> + </parameter> + <parameter name="k"> + <doc xml:space="preserve">the #GQuark id identifying the data element.</doc> + </parameter> + </parameters> + </function-macro> + <function name="dataset_id_remove_no_notify" c:identifier="g_dataset_id_remove_no_notify" introspectable="0"> + <doc xml:space="preserve">Removes an element, without calling its destroy notification +function.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the data previously stored at @key_id, + or %NULL if none.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="dataset_location" transfer-ownership="none"> + <doc xml:space="preserve">the location identifying the dataset.</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="key_id" transfer-ownership="none"> + <doc xml:space="preserve">the #GQuark ID identifying the data element.</doc> + <type name="Quark" c:type="GQuark"/> + </parameter> + </parameters> + </function> + <function-macro name="dataset_id_set_data" c:identifier="g_dataset_id_set_data" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="l"> + <doc xml:space="preserve">the location identifying the dataset.</doc> + </parameter> + <parameter name="k"> + <doc xml:space="preserve">the #GQuark id to identify the data element.</doc> + </parameter> + <parameter name="d"> + <doc xml:space="preserve">the data element.</doc> + </parameter> + </parameters> + </function-macro> + <function name="dataset_id_set_data_full" c:identifier="g_dataset_id_set_data_full" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="dataset_location" transfer-ownership="none"> + <doc xml:space="preserve">the location identifying the dataset.</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="key_id" transfer-ownership="none"> + <doc xml:space="preserve">the #GQuark id to identify the data element.</doc> + <type name="Quark" c:type="GQuark"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data element.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">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.</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function-macro name="dataset_remove_data" c:identifier="g_dataset_remove_data" introspectable="0"> + <doc xml:space="preserve">Removes a data element corresponding to a string. Its destroy +function is called if it has been set.</doc> + <parameters> + <parameter name="l"> + <doc xml:space="preserve">the location identifying the dataset.</doc> + </parameter> + <parameter name="k"> + <doc xml:space="preserve">the string identifying the data element.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="dataset_remove_no_notify" c:identifier="g_dataset_remove_no_notify" introspectable="0"> + <doc xml:space="preserve">Removes an element, without calling its destroy notifier.</doc> + <parameters> + <parameter name="l"> + <doc xml:space="preserve">the location identifying the dataset.</doc> + </parameter> + <parameter name="k"> + <doc xml:space="preserve">the string identifying the data element.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="dataset_set_data" c:identifier="g_dataset_set_data" introspectable="0"> + <doc xml:space="preserve">Sets the data corresponding to the given string identifier.</doc> + <parameters> + <parameter name="l"> + <doc xml:space="preserve">the location identifying the dataset.</doc> + </parameter> + <parameter name="k"> + <doc xml:space="preserve">the string to identify the data element.</doc> + </parameter> + <parameter name="d"> + <doc xml:space="preserve">the data element.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="dataset_set_data_full" c:identifier="g_dataset_set_data_full" introspectable="0"> + <doc xml:space="preserve">Sets the data corresponding to the given string identifier, and the +function to call when the data element is destroyed.</doc> + <parameters> + <parameter name="l"> + <doc xml:space="preserve">the location identifying the dataset.</doc> + </parameter> + <parameter name="k"> + <doc xml:space="preserve">the string to identify the data element.</doc> + </parameter> + <parameter name="d"> + <doc xml:space="preserve">the data element.</doc> + </parameter> + <parameter name="f"> + <doc xml:space="preserve">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.</doc> + </parameter> + </parameters> + </function-macro> + <docsection name="datasets"> + <doc xml:space="preserve">Datasets associate groups of data elements with particular memory +locations. These are useful if you need to associate data with a +structure returned from an external library. Since you cannot modify +the structure, you use its location in memory as the key into a +dataset, where you can associate any number of data elements with it. + +There are two forms of most of the dataset functions. The first form +uses strings to identify the data elements associated with a +location. The second form uses #GQuark identifiers, which are +created with a call to g_quark_from_string() or +g_quark_from_static_string(). The second form is quicker, since it +does not require looking up the string in the hash table of #GQuark +identifiers. + +There is no function to create a dataset. It is automatically +created as soon as you add elements to it. + +To add data elements to a dataset use g_dataset_id_set_data(), +g_dataset_id_set_data_full(), g_dataset_set_data() and +g_dataset_set_data_full(). + +To get data elements from a dataset use g_dataset_id_get_data() and +g_dataset_get_data(). + +To iterate over all data elements in a dataset use +g_dataset_foreach() (not thread-safe). + +To remove data elements from a dataset use +g_dataset_id_remove_data() and g_dataset_remove_data(). + +To destroy a dataset, use g_dataset_destroy().</doc> + </docsection> + <docsection name="date"> + <doc xml:space="preserve">The #GDate data structure represents a day between January 1, Year 1, +and sometime a few thousand years in the future (right now it will go +to the year 65535 or so, but g_date_set_parse() only parses up to the +year 8000 or so - just count on "a few thousand"). #GDate is meant to +represent everyday dates, not astronomical dates or historical dates +or ISO timestamps or the like. It extrapolates the current Gregorian +calendar forward and backward in time; there is no attempt to change +the calendar to match time periods or locations. #GDate does not store +time information; it represents a day. + +The #GDate implementation has several nice features; it is only a +64-bit struct, so storing large numbers of dates is very efficient. It +can keep both a Julian and day-month-year representation of the date, +since some calculations are much easier with one representation or the +other. A Julian representation is simply a count of days since some +fixed day in the past; for #GDate the fixed day is January 1, 1 AD. +("Julian" dates in the #GDate API aren't really Julian dates in the +technical sense; technically, Julian dates count from the start of the +Julian period, Jan 1, 4713 BC). + +#GDate is simple to use. First you need a "blank" date; you can get a +dynamically allocated date from g_date_new(), or you can declare an +automatic variable or array and initialize it by +calling g_date_clear(). A cleared date is safe; it's safe to call +g_date_set_dmy() and the other mutator functions to initialize the +value of a cleared date. However, a cleared date is initially +invalid, meaning that it doesn't represent a day that exists. +It is undefined to call any of the date calculation routines on an +invalid date. If you obtain a date from a user or other +unpredictable source, you should check its validity with the +g_date_valid() predicate. g_date_valid() is also used to check for +errors with g_date_set_parse() and other functions that can +fail. Dates can be invalidated by calling g_date_clear() again. + +It is very important to use the API to access the #GDate +struct. Often only the day-month-year or only the Julian +representation is valid. Sometimes neither is valid. Use the API. + +GLib also features #GDateTime which represents a precise time.</doc> + </docsection> + <docsection name="date-time"> + <doc xml:space="preserve">#GDateTime is a structure that combines a Gregorian date and time +into a single structure. It provides many conversion and methods to +manipulate dates and times. Time precision is provided down to +microseconds and the time can range (proleptically) from 0001-01-01 +00:00:00 to 9999-12-31 23:59:59.999999. #GDateTime follows POSIX +time in the sense that it is oblivious to leap seconds. + +#GDateTime is an immutable object; once it has been created it cannot +be modified further. All modifiers will create a new #GDateTime. +Nearly all such functions can fail due to the date or time going out +of range, in which case %NULL will be returned. + +#GDateTime is reference counted: the reference count is increased by calling +g_date_time_ref() and decreased by calling g_date_time_unref(). When the +reference count drops to 0, the resources allocated by the #GDateTime +structure are released. + +Many parts of the API may produce non-obvious results. As an +example, adding two months to January 31st will yield March 31st +whereas adding one month and then one month again will yield either +March 28th or March 29th. Also note that adding 24 hours is not +always the same as adding one day (since days containing daylight +savings time transitions are either 23 or 25 hours in length). + +#GDateTime is available since GLib 2.26.</doc> + </docsection> + <function name="date_get_days_in_month" c:identifier="g_date_get_days_in_month" moved-to="Date.get_days_in_month"> + <doc xml:space="preserve">Returns the number of days in a month, taking leap +years into account.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">number of days in @month during the @year</doc> + <type name="guint8" c:type="guint8"/> + </return-value> + <parameters> + <parameter name="month" transfer-ownership="none"> + <doc xml:space="preserve">month</doc> + <type name="DateMonth" c:type="GDateMonth"/> + </parameter> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">year</doc> + <type name="DateYear" c:type="GDateYear"/> + </parameter> + </parameters> + </function> + <function name="date_get_monday_weeks_in_year" c:identifier="g_date_get_monday_weeks_in_year" moved-to="Date.get_monday_weeks_in_year"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">number of Mondays in the year</doc> + <type name="guint8" c:type="guint8"/> + </return-value> + <parameters> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">a year</doc> + <type name="DateYear" c:type="GDateYear"/> + </parameter> + </parameters> + </function> + <function name="date_get_sunday_weeks_in_year" c:identifier="g_date_get_sunday_weeks_in_year" moved-to="Date.get_sunday_weeks_in_year"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of weeks in @year</doc> + <type name="guint8" c:type="guint8"/> + </return-value> + <parameters> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">year to count weeks in</doc> + <type name="DateYear" c:type="GDateYear"/> + </parameter> + </parameters> + </function> + <function name="date_is_leap_year" c:identifier="g_date_is_leap_year" moved-to="Date.is_leap_year"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the year is a leap year</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">year to check</doc> + <type name="DateYear" c:type="GDateYear"/> + </parameter> + </parameters> + </function> + <function name="date_strftime" c:identifier="g_date_strftime" moved-to="Date.strftime"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">number of characters written to the buffer, or 0 the buffer was too small</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="s" transfer-ownership="none"> + <doc xml:space="preserve">destination buffer</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="slen" transfer-ownership="none"> + <doc xml:space="preserve">buffer size</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="date" transfer-ownership="none"> + <doc xml:space="preserve">valid #GDate</doc> + <type name="Date" c:type="const GDate*"/> + </parameter> + </parameters> + </function> + <function name="date_valid_day" c:identifier="g_date_valid_day" moved-to="Date.valid_day"> + <doc xml:space="preserve">Returns %TRUE if the day of the month is valid (a day is valid if it's +between 1 and 31 inclusive).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the day is valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="day" transfer-ownership="none"> + <doc xml:space="preserve">day to check</doc> + <type name="DateDay" c:type="GDateDay"/> + </parameter> + </parameters> + </function> + <function name="date_valid_dmy" c:identifier="g_date_valid_dmy" moved-to="Date.valid_dmy"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the date is a valid one</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="day" transfer-ownership="none"> + <doc xml:space="preserve">day</doc> + <type name="DateDay" c:type="GDateDay"/> + </parameter> + <parameter name="month" transfer-ownership="none"> + <doc xml:space="preserve">month</doc> + <type name="DateMonth" c:type="GDateMonth"/> + </parameter> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">year</doc> + <type name="DateYear" c:type="GDateYear"/> + </parameter> + </parameters> + </function> + <function name="date_valid_julian" c:identifier="g_date_valid_julian" moved-to="Date.valid_julian"> + <doc xml:space="preserve">Returns %TRUE if the Julian day is valid. Anything greater than zero +is basically a valid Julian, though there is a 32-bit limit.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the Julian day is valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="julian_date" transfer-ownership="none"> + <doc xml:space="preserve">Julian day to check</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + </parameters> + </function> + <function name="date_valid_month" c:identifier="g_date_valid_month" moved-to="Date.valid_month"> + <doc xml:space="preserve">Returns %TRUE if the month value is valid. The 12 #GDateMonth +enumeration values are the only valid months.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the month is valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="month" transfer-ownership="none"> + <doc xml:space="preserve">month</doc> + <type name="DateMonth" c:type="GDateMonth"/> + </parameter> + </parameters> + </function> + <function name="date_valid_weekday" c:identifier="g_date_valid_weekday" moved-to="Date.valid_weekday"> + <doc xml:space="preserve">Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration +values are the only valid weekdays.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the weekday is valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="weekday" transfer-ownership="none"> + <doc xml:space="preserve">weekday</doc> + <type name="DateWeekday" c:type="GDateWeekday"/> + </parameter> + </parameters> + </function> + <function name="date_valid_year" c:identifier="g_date_valid_year" moved-to="Date.valid_year"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the year is valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="year" transfer-ownership="none"> + <doc xml:space="preserve">year</doc> + <type name="DateYear" c:type="GDateYear"/> + </parameter> + </parameters> + </function> + <function name="dcgettext" c:identifier="g_dcgettext" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the translated string for the given locale category</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the translation domain to use, or %NULL to use + the domain set with textdomain()</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="msgid" transfer-ownership="none"> + <doc xml:space="preserve">message to translate</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="category" transfer-ownership="none"> + <doc xml:space="preserve">a locale category</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="dgettext" c:identifier="g_dgettext" version="2.18"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The translated string</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the translation domain to use, or %NULL to use + the domain set with textdomain()</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="msgid" transfer-ownership="none"> + <doc xml:space="preserve">message to translate</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="dir_make_tmp" c:identifier="g_dir_make_tmp" moved-to="Dir.make_tmp" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="tmpl" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Template for directory name, + as in g_mkdtemp(), basename only, or %NULL for a default template</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="direct_equal" c:identifier="g_direct_equal"> + <doc xml:space="preserve">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)`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the two keys match.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="v1" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="v2" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key to compare with @v1</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="direct_hash" c:identifier="g_direct_hash"> + <doc xml:space="preserve">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)`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a hash value corresponding to the key.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="v" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #gpointer key</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="dngettext" c:identifier="g_dngettext" version="2.18"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The translated string</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the translation domain to use, or %NULL to use + the domain set with textdomain()</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="msgid" transfer-ownership="none"> + <doc xml:space="preserve">message to translate</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="msgid_plural" transfer-ownership="none"> + <doc xml:space="preserve">plural form of the message</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">the quantity for which translation is needed</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + </parameters> + </function> + <function name="double_equal" c:identifier="g_double_equal" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the two keys match.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="v1" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gdouble key</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="v2" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gdouble key to compare with @v1</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="double_hash" c:identifier="g_double_hash" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a hash value corresponding to the key.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="v" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gdouble key</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="dpgettext" c:identifier="g_dpgettext" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The translated string</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the translation domain to use, or %NULL to use + the domain set with textdomain()</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="msgctxtid" transfer-ownership="none"> + <doc xml:space="preserve">a combined message context and message id, separated + by a \004 character</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="msgidoffset" transfer-ownership="none"> + <doc xml:space="preserve">the offset of the message id in @msgctxid</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="dpgettext2" c:identifier="g_dpgettext2" version="2.18"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The translated string</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the translation domain to use, or %NULL to use + the domain set with textdomain()</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">the message context</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="msgid" transfer-ownership="none"> + <doc xml:space="preserve">the message</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="environ_getenv" c:identifier="g_environ_getenv" version="2.32"> + <doc xml:space="preserve">Returns the value of the environment variable @variable in the +provided list @envp.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="envp" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve"> + an environment list (eg, as returned from g_get_environ()), or %NULL + for an empty environment list</doc> + <array c:type="gchar**"> + <type name="filename"/> + </array> + </parameter> + <parameter name="variable" transfer-ownership="none"> + <doc xml:space="preserve">the environment variable to get</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="environ_setenv" c:identifier="g_environ_setenv" version="2.32"> + <doc xml:space="preserve">Sets the environment variable @variable in the provided list +@envp to @value.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + the updated environment list. Free it using g_strfreev().</doc> + <array c:type="gchar**"> + <type name="filename"/> + </array> + </return-value> + <parameters> + <parameter name="envp" transfer-ownership="full" nullable="1" allow-none="1"> + <doc xml:space="preserve"> + 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</doc> + <array c:type="gchar**"> + <type name="filename"/> + </array> + </parameter> + <parameter name="variable" transfer-ownership="none"> + <doc xml:space="preserve">the environment variable to set, must not + contain '='</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value for to set the variable to</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="overwrite" transfer-ownership="none"> + <doc xml:space="preserve">whether to change the variable if it already exists</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="environ_unsetenv" c:identifier="g_environ_unsetenv" version="2.32"> + <doc xml:space="preserve">Removes the environment variable @variable from the provided +environment @envp.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + the updated environment list. Free it using g_strfreev().</doc> + <array c:type="gchar**"> + <type name="filename"/> + </array> + </return-value> + <parameters> + <parameter name="envp" transfer-ownership="full" nullable="1" allow-none="1"> + <doc xml:space="preserve"> + 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</doc> + <array c:type="gchar**"> + <type name="filename"/> + </array> + </parameter> + <parameter name="variable" transfer-ownership="none"> + <doc xml:space="preserve">the environment variable to remove, must not + contain '='</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <docsection name="error_reporting"> + <doc xml:space="preserve">GLib provides a standard method of reporting errors from a called +function to the calling code. (This is the same problem solved by +exceptions in other languages.) It's important to understand that +this method is both a data type (the #GError struct) and a [set of +rules][gerror-rules]. If you use #GError incorrectly, then your code will not +properly interoperate with other code that uses #GError, and users +of your API will probably get confused. In most cases, [using #GError is +preferred over numeric error codes][gerror-comparison], but there are +situations where numeric error codes are useful for performance. + +First and foremost: #GError should only be used to report recoverable +runtime errors, never to report programming errors. If the programmer +has screwed up, then you should use g_warning(), g_return_if_fail(), +g_assert(), g_error(), or some similar facility. (Incidentally, +remember that the g_error() function should only be used for +programming errors, it should not be used to print any error +reportable via #GError.) + +Examples of recoverable runtime errors are "file not found" or +"failed to parse input." Examples of programming errors are "NULL +passed to strcmp()" or "attempted to free the same pointer twice." +These two kinds of errors are fundamentally different: runtime errors +should be handled or reported to the user, programming errors should +be eliminated by fixing the bug in the program. This is why most +functions in GLib and GTK+ do not use the #GError facility. + +Functions that can fail take a return location for a #GError as their +last argument. On error, a new #GError instance will be allocated and +returned to the caller via this argument. For example: +|[<!-- language="C" --> +gboolean g_file_get_contents (const gchar *filename, + gchar **contents, + gsize *length, + GError **error); +]| +If you pass a non-%NULL value for the `error` argument, it should +point to a location where an error can be placed. For example: +|[<!-- language="C" --> +gchar *contents; +GError *err = NULL; + +g_file_get_contents ("foo.txt", &contents, NULL, &err); +g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL)); +if (err != NULL) + { + // Report error to user, and free error + g_assert (contents == NULL); + fprintf (stderr, "Unable to read file: %s\n", err->message); + g_error_free (err); + } +else + { + // Use file contents + g_assert (contents != NULL); + } +]| +Note that `err != NULL` in this example is a reliable indicator +of whether g_file_get_contents() failed. Additionally, +g_file_get_contents() returns a boolean which +indicates whether it was successful. + +Because g_file_get_contents() returns %FALSE on failure, if you +are only interested in whether it failed and don't need to display +an error message, you can pass %NULL for the @error argument: +|[<!-- language="C" --> +if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors + // no error occurred + ; +else + // error + ; +]| + +The #GError object contains three fields: @domain indicates the module +the error-reporting function is located in, @code indicates the specific +error that occurred, and @message is a user-readable error message with +as many details as possible. Several functions are provided to deal +with an error received from a called function: g_error_matches() +returns %TRUE if the error matches a given domain and code, +g_propagate_error() copies an error into an error location (so the +calling function will receive it), and g_clear_error() clears an +error location by freeing the error and resetting the location to +%NULL. To display an error to the user, simply display the @message, +perhaps along with additional context known only to the calling +function (the file being opened, or whatever - though in the +g_file_get_contents() case, the @message already contains a filename). + +Note, however, that many error messages are too technical to display to the +user in an application, so prefer to use g_error_matches() to categorize errors +from called functions, and build an appropriate error message for the context +within your application. Error messages from a #GError are more appropriate +to be printed in system logs or on the command line. They are typically +translated. + +When implementing a function that can report errors, the basic +tool is g_set_error(). Typically, if a fatal error occurs you +want to g_set_error(), then return immediately. g_set_error() +does nothing if the error location passed to it is %NULL. +Here's an example: +|[<!-- language="C" --> +gint +foo_open_file (GError **error) +{ + gint fd; + int saved_errno; + + g_return_val_if_fail (error == NULL || *error == NULL, -1); + + fd = open ("file.txt", O_RDONLY); + saved_errno = errno; + + if (fd < 0) + { + g_set_error (error, + FOO_ERROR, // error domain + FOO_ERROR_BLAH, // error code + "Failed to open file: %s", // error message format string + g_strerror (saved_errno)); + return -1; + } + else + return fd; +} +]| + +Things are somewhat more complicated if you yourself call another +function that can report a #GError. If the sub-function indicates +fatal errors in some way other than reporting a #GError, such as +by returning %TRUE on success, you can simply do the following: +|[<!-- language="C" --> +gboolean +my_function_that_can_fail (GError **err) +{ + g_return_val_if_fail (err == NULL || *err == NULL, FALSE); + + if (!sub_function_that_can_fail (err)) + { + // assert that error was set by the sub-function + g_assert (err == NULL || *err != NULL); + return FALSE; + } + + // otherwise continue, no error occurred + g_assert (err == NULL || *err == NULL); +} +]| + +If the sub-function does not indicate errors other than by +reporting a #GError (or if its return value does not reliably indicate +errors) you need to create a temporary #GError +since the passed-in one may be %NULL. g_propagate_error() is +intended for use in this case. +|[<!-- language="C" --> +gboolean +my_function_that_can_fail (GError **err) +{ + GError *tmp_error; + + g_return_val_if_fail (err == NULL || *err == NULL, FALSE); + + tmp_error = NULL; + sub_function_that_can_fail (&tmp_error); + + if (tmp_error != NULL) + { + // store tmp_error in err, if err != NULL, + // otherwise call g_error_free() on tmp_error + g_propagate_error (err, tmp_error); + return FALSE; + } + + // otherwise continue, no error occurred +} +]| + +Error pileups are always a bug. For example, this code is incorrect: +|[<!-- language="C" --> +gboolean +my_function_that_can_fail (GError **err) +{ + GError *tmp_error; + + g_return_val_if_fail (err == NULL || *err == NULL, FALSE); + + tmp_error = NULL; + sub_function_that_can_fail (&tmp_error); + other_function_that_can_fail (&tmp_error); + + if (tmp_error != NULL) + { + g_propagate_error (err, tmp_error); + return FALSE; + } +} +]| +@tmp_error should be checked immediately after sub_function_that_can_fail(), +and either cleared or propagated upward. The rule is: after each error, +you must either handle the error, or return it to the calling function. + +Note that passing %NULL for the error location is the equivalent +of handling an error by always doing nothing about it. So the +following code is fine, assuming errors in sub_function_that_can_fail() +are not fatal to my_function_that_can_fail(): +|[<!-- language="C" --> +gboolean +my_function_that_can_fail (GError **err) +{ + GError *tmp_error; + + g_return_val_if_fail (err == NULL || *err == NULL, FALSE); + + sub_function_that_can_fail (NULL); // ignore errors + + tmp_error = NULL; + other_function_that_can_fail (&tmp_error); + + if (tmp_error != NULL) + { + g_propagate_error (err, tmp_error); + return FALSE; + } +} +]| + +Note that passing %NULL for the error location ignores errors; +it's equivalent to +`try { sub_function_that_can_fail (); } catch (...) {}` +in C++. It does not mean to leave errors unhandled; it means +to handle them by doing nothing. + +Error domains and codes are conventionally named as follows: + +- The error domain is called <NAMESPACE>_<MODULE>_ERROR, + for example %G_SPAWN_ERROR or %G_THREAD_ERROR: + |[<!-- language="C" --> + #define G_SPAWN_ERROR g_spawn_error_quark () + + G_DEFINE_QUARK (g-spawn-error-quark, g_spawn_error) + ]| + +- The quark function for the error domain is called + <namespace>_<module>_error_quark, + for example g_spawn_error_quark() or g_thread_error_quark(). + +- The error codes are in an enumeration called + <Namespace><Module>Error; + for example, #GThreadError or #GSpawnError. + +- Members of the error code enumeration are called + <NAMESPACE>_<MODULE>_ERROR_<CODE>, + for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN. + +- If there's a "generic" or "unknown" error code for unrecoverable + errors it doesn't make sense to distinguish with specific codes, + it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED, + for example %G_SPAWN_ERROR_FAILED. In the case of error code + enumerations that may be extended in future releases, you should + generally not handle this error code explicitly, but should + instead treat any unrecognized error code as equivalent to + FAILED. + +## Comparison of #GError and traditional error handling # {#gerror-comparison} + +#GError has several advantages over traditional numeric error codes: +importantly, tools like +[gobject-introspection](https://developer.gnome.org/gi/stable/) understand +#GErrors and convert them to exceptions in bindings; the message includes +more information than just a code; and use of a domain helps prevent +misinterpretation of error codes. + +#GError has disadvantages though: it requires a memory allocation, and +formatting the error message string has a performance overhead. This makes it +unsuitable for use in retry loops where errors are a common case, rather than +being unusual. For example, using %G_IO_ERROR_WOULD_BLOCK means hitting these +overheads in the normal control flow. String formatting overhead can be +eliminated by using g_set_error_literal() in some cases. + +These performance issues can be compounded if a function wraps the #GErrors +returned by the functions it calls: this multiplies the number of allocations +and string formatting operations. This can be partially mitigated by using +g_prefix_error(). + +## Rules for use of #GError # {#gerror-rules} + +Summary of rules for use of #GError: + +- Do not report programming errors via #GError. + +- The last argument of a function that returns an error should + be a location where a #GError can be placed (i.e. `GError **error`). + If #GError is used with varargs, the `GError**` should be the last + argument before the `...`. + +- The caller may pass %NULL for the `GError**` if they are not interested + in details of the exact error that occurred. + +- If %NULL is passed for the `GError**` argument, then errors should + not be returned to the caller, but your function should still + abort and return if an error occurs. That is, control flow should + not be affected by whether the caller wants to get a #GError. + +- If a #GError is reported, then your function by definition had a + fatal failure and did not complete whatever it was supposed to do. + If the failure was not fatal, then you handled it and you should not + report it. If it was fatal, then you must report it and discontinue + whatever you were doing immediately. + +- If a #GError is reported, out parameters are not guaranteed to + be set to any defined value. + +- A `GError*` must be initialized to %NULL before passing its address + to a function that can report errors. + +- #GError structs must not be stack-allocated. + +- "Piling up" errors is always a bug. That is, if you assign a + new #GError to a `GError*` that is non-%NULL, thus overwriting + the previous error, it indicates that you should have aborted + the operation instead of continuing. If you were able to continue, + you should have cleared the previous error with g_clear_error(). + g_set_error() will complain if you pile up errors. + +- By convention, if you return a boolean value indicating success + then %TRUE means success and %FALSE means failure. Avoid creating + functions which have a boolean return value and a #GError parameter, + but where the boolean does something other than signal whether the + #GError is set. Among other problems, it requires C callers to allocate + a temporary error. Instead, provide a `gboolean *` out parameter. + There are functions in GLib itself such as g_key_file_has_key() that + are hard to use because of this. If %FALSE is returned, the error must + be set to a non-%NULL value. One exception to this is that in situations + that are already considered to be undefined behaviour (such as when a + g_return_val_if_fail() check fails), the error need not be set. + Instead of checking separately whether the error is set, callers + should ensure that they do not provoke undefined behaviour, then + assume that the error will be set on failure. + +- A %NULL return value is also frequently used to mean that an error + occurred. You should make clear in your documentation whether %NULL + is a valid return value in non-error cases; if %NULL is a valid value, + then users must check whether an error was returned to see if the + function succeeded. + +- When implementing a function that can report errors, you may want + to add a check at the top of your function that the error return + location is either %NULL or contains a %NULL error (e.g. + `g_return_if_fail (error == NULL || *error == NULL);`). + +## Extended #GError Domains # {#gerror-extended-domains} + +Since GLib 2.68 it is possible to extend the #GError type. This is +done with the G_DEFINE_EXTENDED_ERROR() macro. To create an +extended #GError type do something like this in the header file: +|[<!-- language="C" --> +typedef enum +{ + MY_ERROR_BAD_REQUEST, +} MyError; +#define MY_ERROR (my_error_quark ()) +GQuark my_error_quark (void); +int +my_error_get_parse_error_id (GError *error); +const char * +my_error_get_bad_request_details (GError *error); +]| +and in implementation: +|[<!-- language="C" --> +typedef struct +{ + int parse_error_id; + char *bad_request_details; +} MyErrorPrivate; + +static void +my_error_private_init (MyErrorPrivate *priv) +{ + priv->parse_error_id = -1; + // No need to set priv->bad_request_details to NULL, + // the struct is initialized with zeros. +} + +static void +my_error_private_copy (const MyErrorPrivate *src_priv, MyErrorPrivate *dest_priv) +{ + dest_priv->parse_error_id = src_priv->parse_error_id; + dest_priv->bad_request_details = g_strdup (src_priv->bad_request_details); +} + +static void +my_error_private_clear (MyErrorPrivate *priv) +{ + g_free (priv->bad_request_details); +} + +// This defines the my_error_get_private and my_error_quark functions. +G_DEFINE_EXTENDED_ERROR (MyError, my_error) + +int +my_error_get_parse_error_id (GError *error) +{ + MyErrorPrivate *priv = my_error_get_private (error); + g_return_val_if_fail (priv != NULL, -1); + return priv->parse_error_id; +} + +const char * +my_error_get_bad_request_details (GError *error) +{ + MyErrorPrivate *priv = my_error_get_private (error); + g_return_val_if_fail (priv != NULL, NULL); + g_return_val_if_fail (error->code != MY_ERROR_BAD_REQUEST, NULL); + return priv->bad_request_details; +} + +static void +my_error_set_bad_request (GError **error, + const char *reason, + int error_id, + const char *details) +{ + MyErrorPrivate *priv; + g_set_error (error, MY_ERROR, MY_ERROR_BAD_REQUEST, "Invalid request: %s", reason); + if (error != NULL && *error != NULL) + { + priv = my_error_get_private (error); + g_return_val_if_fail (priv != NULL, NULL); + priv->parse_error_id = error_id; + priv->bad_request_details = g_strdup (details); + } +} +]| +An example of use of the error could be: +|[<!-- language="C" --> +gboolean +send_request (GBytes *request, GError **error) +{ + ParseFailedStatus *failure = validate_request (request); + if (failure != NULL) + { + my_error_set_bad_request (error, failure->reason, failure->error_id, failure->details); + parse_failed_status_free (failure); + return FALSE; + } + + return send_one (request, error); +} +]| + +Please note that if you are a library author and your library +exposes an existing error domain, then you can't make this error +domain an extended one without breaking ABI. This is because +earlier it was possible to create an error with this error domain +on the stack and then copy it with g_error_copy(). If the new +version of your library makes the error domain an extended one, +then g_error_copy() called by code that allocated the error on the +stack will try to copy more data than it used to, which will lead +to undefined behavior. You must not stack-allocate errors with an +extended error domain, and it is bad practice to stack-allocate any +other #GErrors. + +Extended error domains in unloadable plugins/modules are not +supported.</doc> + </docsection> + <function name="file_error_from_errno" c:identifier="g_file_error_from_errno"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">#GFileError corresponding to the given @errno</doc> + <type name="FileError" c:type="GFileError"/> + </return-value> + <parameters> + <parameter name="err_no" transfer-ownership="none"> + <doc xml:space="preserve">an "errno" value</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="file_error_quark" c:identifier="g_file_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="file_get_contents" c:identifier="g_file_get_contents" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if an error occurred</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">name of a file to read contents from, in the GLib file name encoding</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="contents" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">location to store an allocated string, use g_free() to free + the returned string</doc> + <array length="2" zero-terminated="0" c:type="gchar**"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">location to store length in bytes of the contents, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </function> + <function name="file_open_tmp" c:identifier="g_file_open_tmp" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="tmpl" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Template for file name, as in + g_mkstemp(), basename only, or %NULL for a default template</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="name_used" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">location to store actual name used, + or %NULL</doc> + <type name="filename" c:type="gchar**"/> + </parameter> + </parameters> + </function> + <function name="file_read_link" c:identifier="g_file_read_link" version="2.4" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A newly-allocated string with the contents of + the symbolic link, or %NULL if an error occurred.</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">the symbolic link</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="file_set_contents" c:identifier="g_file_set_contents" version="2.8" throws="1"> + <doc xml:space="preserve">Writes all of @contents to a file named @filename. This is a convenience +wrapper around calling g_file_set_contents_full() with `flags` set to +`G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING` and +`mode` set to `0666`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if an error occurred</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">name of a file to write @contents to, in the GLib file name + encoding</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="contents" transfer-ownership="none"> + <doc xml:space="preserve">string to write to the file</doc> + <array length="2" zero-terminated="0" c:type="const gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">length of @contents, or -1 if @contents is a nul-terminated string</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function name="file_set_contents_full" c:identifier="g_file_set_contents_full" version="2.66" throws="1"> + <doc xml:space="preserve">Writes all of @contents to a file named @filename, with good error checking. +If a file called @filename already exists it will be overwritten. + +@flags control the properties of the write operation: whether it’s atomic, +and what the tradeoff is between returning quickly or being resilient to +system crashes. + +As this function performs file I/O, it is recommended to not call it anywhere +where blocking would cause problems, such as in the main loop of a graphical +application. In particular, if @flags has any value other than +%G_FILE_SET_CONTENTS_NONE then this function may call `fsync()`. + +If %G_FILE_SET_CONTENTS_CONSISTENT is set in @flags, the operation 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), and if + %G_FILE_SET_CONTENTS_CONSISTENT is set in @flags, 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, unless %G_FILE_SET_CONTENTS_DURABLE and + %G_FILE_SET_CONTENTS_CONSISTENT are set in @flags. + +- 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. + +If the file didn’t exist before and is created, it will be given the +permissions from @mode. Otherwise, the permissions of the existing file may +be changed to @mode depending on @flags, or they may remain unchanged.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if an error occurred</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">name of a file to write @contents to, in the GLib file name + encoding</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="contents" transfer-ownership="none"> + <doc xml:space="preserve">string to write to the file</doc> + <array length="2" zero-terminated="0" c:type="const gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">length of @contents, or -1 if @contents is a nul-terminated string</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags controlling the safety vs speed of the operation</doc> + <type name="FileSetContentsFlags" c:type="GFileSetContentsFlags"/> + </parameter> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve">file mode, as passed to `open()`; typically this will be `0666`</doc> + <type name="gint" c:type="int"/> + </parameter> + </parameters> + </function> + <function name="file_test" c:identifier="g_file_test"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether a test was %TRUE</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">a filename to test in the + GLib file name encoding</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="test" transfer-ownership="none"> + <doc xml:space="preserve">bitfield of #GFileTest flags</doc> + <type name="FileTest" c:type="GFileTest"/> + </parameter> + </parameters> + </function> + <function name="filename_display_basename" c:identifier="g_filename_display_basename" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string containing + a rendition of the basename of the filename in valid UTF-8</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">an absolute pathname in the + GLib file name encoding</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="filename_display_name" c:identifier="g_filename_display_name" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string containing + a rendition of the filename in valid UTF-8</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">a pathname hopefully in the + GLib file name encoding</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="filename_from_uri" c:identifier="g_filename_from_uri" throws="1"> + <doc xml:space="preserve">Converts an escaped ASCII-encoded URI to a local filename in the +encoding used for filenames.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated string holding + the resulting filename, or %NULL on an error.</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a uri describing a filename (escaped, encoded in ASCII).</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="hostname" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">Location to store hostname for the URI. + If there is no hostname in the URI, %NULL will be + stored in this location.</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </function> + <function name="filename_from_utf8" c:identifier="g_filename_from_utf8" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + The converted string, or %NULL on an error.</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="utf8string" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the length of the string, or -1 if the string is + nul-terminated.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">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.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of bytes stored in + the output buffer (not including the terminating nul).</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </function> + <function name="filename_to_uri" c:identifier="g_filename_to_uri" throws="1"> + <doc xml:space="preserve">Converts an absolute filename to an escaped ASCII-encoded URI, with the path +component following Section 3.3. of RFC 2396.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated string holding the resulting + URI, or %NULL on an error.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">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</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="hostname" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A UTF-8 encoded hostname, or %NULL for none.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="filename_to_utf8" c:identifier="g_filename_to_utf8" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">The converted string, or %NULL on an error.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="opsysstring" transfer-ownership="none"> + <doc xml:space="preserve">a string in the encoding for filenames</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">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)</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">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.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of bytes stored in the output + buffer (not including the terminating nul).</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </function> + <docsection name="fileutils"> + <doc xml:space="preserve">Do not use these APIs unless you are porting a POSIX application to Windows. +A more high-level file access API is provided as GIO — see the documentation +for #GFile. + +There is a group of functions which wrap the common POSIX functions +dealing with filenames (g_open(), g_rename(), g_mkdir(), g_stat(), +g_unlink(), g_remove(), g_fopen(), g_freopen()). The point of these +wrappers is to make it possible to handle file names with any Unicode +characters in them on Windows without having to use ifdefs and the +wide character API in the application code. + +On some Unix systems, these APIs may be defined as identical to their POSIX +counterparts. For this reason, you must check for and include the necessary +header files (such as `fcntl.h`) before using functions like g_creat(). You +must also define the relevant feature test macros. + +The pathname argument should be in the GLib file name encoding. +On POSIX this is the actual on-disk encoding which might correspond +to the locale settings of the process (or the `G_FILENAME_ENCODING` +environment variable), or not. + +On Windows the GLib file name encoding is UTF-8. Note that the +Microsoft C library does not use UTF-8, but has separate APIs for +current system code page and wide characters (UTF-16). The GLib +wrappers call the wide character API if present (on modern Windows +systems), otherwise convert to/from the system code page. + +Another group of functions allows to open and read directories +in the GLib file name encoding. These are g_dir_open(), +g_dir_read_name(), g_dir_rewind(), g_dir_close().</doc> + </docsection> + <function name="find_program_in_path" c:identifier="g_find_program_in_path"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly-allocated + string with the absolute path, or %NULL</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="program" transfer-ownership="none"> + <doc xml:space="preserve">a program name in the GLib file name encoding</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="format_size" c:identifier="g_format_size" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated formatted string containing + a human readable file size</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">a size in bytes</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + </parameters> + </function> + <function name="format_size_for_display" c:identifier="g_format_size_for_display" version="2.16" deprecated="1" deprecated-version="2.30"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">This function is broken due to its use of SI + suffixes to denote IEC units. Use g_format_size() instead.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated formatted string + containing a human readable file size</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">a size in bytes</doc> + <type name="gint64" c:type="goffset"/> + </parameter> + </parameters> + </function> + <function name="format_size_full" c:identifier="g_format_size_full" version="2.30"> + <doc xml:space="preserve">Formats a size. + +This function is similar to g_format_size() but allows for flags +that modify the output. See #GFormatSizeFlags.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated formatted string + containing a human readable file size</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">a size in bytes</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">#GFormatSizeFlags to modify the output</doc> + <type name="FormatSizeFlags" c:type="GFormatSizeFlags"/> + </parameter> + </parameters> + </function> + <function name="fprintf" c:identifier="g_fprintf" version="2.2" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes printed.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">the stream to write to.</doc> + <type name="gpointer" c:type="FILE*"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a standard printf() format string, but notice + [string precision pitfalls][string-precision]</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the arguments to insert in the output.</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="free" c:identifier="g_free"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mem" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the memory to free</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="get_application_name" c:identifier="g_get_application_name" version="2.2"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">human-readable application + name. May return %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + </function> + <function name="get_charset" c:identifier="g_get_charset"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the returned charset is UTF-8</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="charset" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for character set + name, or %NULL.</doc> + <type name="utf8" c:type="const char**"/> + </parameter> + </parameters> + </function> + <function name="get_codeset" c:identifier="g_get_codeset"> + <doc xml:space="preserve">Gets the character set for the current locale.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string containing the name + of the character set. This string must be freed with g_free().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + </function> + <function name="get_console_charset" c:identifier="g_get_console_charset" version="2.62"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the returned charset is UTF-8</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="charset" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for character set + name, or %NULL.</doc> + <type name="utf8" c:type="const char**"/> + </parameter> + </parameters> + </function> + <function name="get_current_dir" c:identifier="g_get_current_dir"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the current directory</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + </function> + <function name="get_current_time" c:identifier="g_get_current_time" deprecated="1" deprecated-version="2.62"> + <doc xml:space="preserve">Equivalent to the UNIX gettimeofday() function, but portable. + +You may find g_get_real_time() to be more convenient.</doc> + <doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use g_get_real_time() + instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">#GTimeVal structure in which to store current time.</doc> + <type name="TimeVal" c:type="GTimeVal*"/> + </parameter> + </parameters> + </function> + <function name="get_environ" c:identifier="g_get_environ" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + the list of environment variables</doc> + <array c:type="gchar**"> + <type name="filename"/> + </array> + </return-value> + </function> + <function name="get_filename_charsets" c:identifier="g_get_filename_charsets" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the filename encoding is UTF-8.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="filename_charsets" direction="out" caller-allocates="0" transfer-ownership="none"> + <doc xml:space="preserve"> + return location for the %NULL-terminated list of encoding names</doc> + <array c:type="const gchar***"> + <type name="utf8" c:type="gchar**"/> + </array> + </parameter> + </parameters> + </function> + <function name="get_home_dir" c:identifier="g_get_home_dir"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the current user's home directory</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + </function> + <function name="get_host_name" c:identifier="g_get_host_name" version="2.8"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the host name of the machine.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + </function> + <function name="get_language_names" c:identifier="g_get_language_names" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a %NULL-terminated array of strings owned by GLib + that must not be modified or freed.</doc> + <array c:type="const gchar* const*"> + <type name="utf8"/> + </array> + </return-value> + </function> + <function name="get_language_names_with_category" c:identifier="g_get_language_names_with_category" version="2.58"> + <doc xml:space="preserve">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").</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <array c:type="const gchar* const*"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="category_name" transfer-ownership="none"> + <doc xml:space="preserve">a locale category name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="get_locale_variants" c:identifier="g_get_locale_variants" version="2.28"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly + allocated array of newly allocated strings with the locale variants. Free with + g_strfreev().</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="locale" transfer-ownership="none"> + <doc xml:space="preserve">a locale identifier</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="get_monotonic_time" c:identifier="g_get_monotonic_time" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the monotonic time, in microseconds</doc> + <type name="gint64" c:type="gint64"/> + </return-value> + </function> + <function name="get_num_processors" c:identifier="g_get_num_processors" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of schedulable threads, always greater than 0</doc> + <type name="guint" c:type="guint"/> + </return-value> + </function> + <function name="get_os_info" c:identifier="g_get_os_info" version="2.64"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">The associated value for the requested key or %NULL if + this information is not provided.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="key_name" transfer-ownership="none"> + <doc xml:space="preserve">a key for the OS info being requested, for example %G_OS_INFO_KEY_NAME.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="get_prgname" c:identifier="g_get_prgname"> + <doc xml:space="preserve">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].</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + </function> + <function name="get_real_name" c:identifier="g_get_real_name"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the user's real name.</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + </function> + <function name="get_real_time" c:identifier="g_get_real_time" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of microseconds since January 1, 1970 UTC.</doc> + <type name="gint64" c:type="gint64"/> + </return-value> + </function> + <function name="get_system_config_dirs" c:identifier="g_get_system_config_dirs" version="2.6"> + <doc xml:space="preserve">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. + +The return value is cached and modifying it at runtime is not supported, as +it’s not thread-safe to modify environment variables at runtime.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve"> + a %NULL-terminated array of strings owned by GLib that must not be + modified or freed.</doc> + <array c:type="const gchar* const*"> + <type name="filename"/> + </array> + </return-value> + </function> + <function name="get_system_data_dirs" c:identifier="g_get_system_data_dirs" version="2.6"> + <doc xml:space="preserve">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. + +The return value is cached and modifying it at runtime is not supported, as +it’s not thread-safe to modify environment variables at runtime.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve"> + a %NULL-terminated array of strings owned by GLib that must not be + modified or freed.</doc> + <array c:type="const gchar* const*"> + <type name="filename"/> + </array> + </return-value> + </function> + <function name="get_tmp_dir" c:identifier="g_get_tmp_dir"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the directory to use for temporary files.</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + </function> + <function name="get_user_cache_dir" c:identifier="g_get_user_cache_dir" version="2.6"> + <doc xml:space="preserve">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). + +The return value is cached and modifying it at runtime is not supported, as +it’s not thread-safe to modify environment variables at runtime.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a string owned by GLib that + must not be modified or freed.</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + </function> + <function name="get_user_config_dir" c:identifier="g_get_user_config_dir" version="2.6"> + <doc xml:space="preserve">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. + +The return value is cached and modifying it at runtime is not supported, as +it’s not thread-safe to modify environment variables at runtime.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a string owned by GLib that + must not be modified or freed.</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + </function> + <function name="get_user_data_dir" c:identifier="g_get_user_data_dir" version="2.6"> + <doc xml:space="preserve">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. + +The return value is cached and modifying it at runtime is not supported, as +it’s not thread-safe to modify environment variables at runtime.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a string owned by GLib that must + not be modified or freed.</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + </function> + <function name="get_user_name" c:identifier="g_get_user_name"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the user name of the current user.</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + </function> + <function name="get_user_runtime_dir" c:identifier="g_get_user_runtime_dir" version="2.28"> + <doc xml:space="preserve">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. + +The return value is cached and modifying it at runtime is not supported, as +it’s not thread-safe to modify environment variables at runtime.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a string owned by GLib that must not be + modified or freed.</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + </function> + <function name="get_user_special_dir" c:identifier="g_get_user_special_dir" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="directory" transfer-ownership="none"> + <doc xml:space="preserve">the logical id of special directory</doc> + <type name="UserDirectory" c:type="GUserDirectory"/> + </parameter> + </parameters> + </function> + <function name="getenv" c:identifier="g_getenv"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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().</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="variable" transfer-ownership="none"> + <doc xml:space="preserve">the environment variable to get</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <docsection name="ghostutils"> + <doc xml:space="preserve">Functions for manipulating internet hostnames; in particular, for +converting between Unicode and ASCII-encoded forms of +Internationalized Domain Names (IDNs). + +The +[Internationalized Domain Names for Applications (IDNA)](http://www.ietf.org/rfc/rfc3490.txt) +standards allow for the use +of Unicode domain names in applications, while providing +backward-compatibility with the old ASCII-only DNS, by defining an +ASCII-Compatible Encoding of any given Unicode name, which can be +used with non-IDN-aware applications and protocols. (For example, +"Παν語.org" maps to "xn--4wa8awb4637h.org".)</doc> + </docsection> + <docsection name="gstrvbuilder"> + <doc xml:space="preserve">#GStrvBuilder is a method of easily building dynamically sized +NULL-terminated string arrays. + +The following example shows how to build a two element array: + +|[<!-- language="C" --> + g_autoptr(GStrvBuilder) builder = g_strv_builder_new (); + g_strv_builder_add (builder, "hello"); + g_strv_builder_add (builder, "world"); + g_auto(GStrv) array = g_strv_builder_end (builder); +]|</doc> + </docsection> + <docsection name="gunix"> + <doc xml:space="preserve">Most of GLib is intended to be portable; in contrast, this set of +functions is designed for programs which explicitly target UNIX, +or are using it to build higher level abstractions which would be +conditionally compiled if the platform matches G_OS_UNIX. + +To use these functions, you must explicitly include the +"glib-unix.h" header.</doc> + </docsection> + <function name="hash_table_add" c:identifier="g_hash_table_add" moved-to="HashTable.add" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key did not exist yet</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="key" transfer-ownership="full" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key to insert</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="hash_table_contains" c:identifier="g_hash_table_contains" moved-to="HashTable.contains" version="2.32"> + <doc xml:space="preserve">Checks if @key is in @hash_table.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @key is in @hash_table, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key to check</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="hash_table_destroy" c:identifier="g_hash_table_destroy" moved-to="HashTable.destroy"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function-macro name="hash_table_freeze" c:identifier="g_hash_table_freeze" introspectable="0"> + <doc xml:space="preserve">This function is deprecated and will be removed in the next major +release of GLib. It does nothing.</doc> + <parameters> + <parameter name="hash_table"> + <doc xml:space="preserve">a #GHashTable</doc> + </parameter> + </parameters> + </function-macro> + <function name="hash_table_insert" c:identifier="g_hash_table_insert" moved-to="HashTable.insert"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key did not exist yet</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key to insert</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the value to associate with the key</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="hash_table_lookup" c:identifier="g_hash_table_lookup" moved-to="HashTable.lookup"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the associated value, or %NULL if the key is not found</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the key to look up</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="hash_table_lookup_extended" c:identifier="g_hash_table_lookup_extended" moved-to="HashTable.lookup_extended"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key was found in the #GHashTable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="lookup_key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the key to look up</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="orig_key" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the original key</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + <parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the value associated +with the key</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + </parameters> + </function> + <function name="hash_table_remove" c:identifier="g_hash_table_remove" moved-to="HashTable.remove"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key was found and removed from the #GHashTable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the key to remove</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="hash_table_remove_all" c:identifier="g_hash_table_remove_all" moved-to="HashTable.remove_all" version="2.12"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="hash_table_replace" c:identifier="g_hash_table_replace" moved-to="HashTable.replace"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key did not exist yet</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a key to insert</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the value to associate with the key</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="hash_table_size" c:identifier="g_hash_table_size" moved-to="HashTable.size"> + <doc xml:space="preserve">Returns the number of elements contained in the #GHashTable.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of key/value pairs in the #GHashTable.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="hash_table_steal" c:identifier="g_hash_table_steal" moved-to="HashTable.steal"> + <doc xml:space="preserve">Removes a key and its associated value from a #GHashTable without +calling the key and value destroy functions.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key was found and removed from the #GHashTable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the key to remove</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="hash_table_steal_all" c:identifier="g_hash_table_steal_all" moved-to="HashTable.steal_all" version="2.12"> + <doc xml:space="preserve">Removes all keys and their associated values from a #GHashTable +without calling the key and value destroy functions.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="hash_table_steal_extended" c:identifier="g_hash_table_steal_extended" moved-to="HashTable.steal_extended" version="2.58"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key was found in the #GHashTable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="lookup_key" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the key to look up</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="stolen_key" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the + original key</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + <parameter name="stolen_value" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">return location + for the value associated with the key</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + </parameters> + </function> + <function-macro name="hash_table_thaw" c:identifier="g_hash_table_thaw" introspectable="0"> + <doc xml:space="preserve">This function is deprecated and will be removed in the next major +release of GLib. It does nothing.</doc> + <parameters> + <parameter name="hash_table"> + <doc xml:space="preserve">a #GHashTable</doc> + </parameter> + </parameters> + </function-macro> + <function name="hash_table_unref" c:identifier="g_hash_table_unref" moved-to="HashTable.unref" version="2.10"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hash_table" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GHashTable</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <docsection name="hash_tables"> + <doc xml:space="preserve">A #GHashTable provides associations between keys and values which is +optimized so that given a key, the associated value can be found, +inserted or removed in amortized O(1). All operations going through +each element take O(n) time (list all keys/values, table resize, etc.). + +Note that neither keys nor values are copied when inserted into the +#GHashTable, so they must exist for the lifetime of the #GHashTable. +This means that the use of static strings is OK, but temporary +strings (i.e. those created in buffers and those returned by GTK +widgets) should be copied with g_strdup() before being inserted. + +If keys or values are dynamically allocated, you must be careful to +ensure that they are freed when they are removed from the +#GHashTable, and also when they are overwritten by new insertions +into the #GHashTable. It is also not advisable to mix static strings +and dynamically-allocated strings in a #GHashTable, because it then +becomes difficult to determine whether the string should be freed. + +To create a #GHashTable, use g_hash_table_new(). + +To insert a key and value into a #GHashTable, use +g_hash_table_insert(). + +To look up a value corresponding to a given key, use +g_hash_table_lookup() and g_hash_table_lookup_extended(). + +g_hash_table_lookup_extended() can also be used to simply +check if a key is present in the hash table. + +To remove a key and value, use g_hash_table_remove(). + +To call a function for each key and value pair use +g_hash_table_foreach() or use an iterator to iterate over the +key/value pairs in the hash table, see #GHashTableIter. The iteration order +of a hash table is not defined, and you must not rely on iterating over +keys/values in the same order as they were inserted. + +To destroy a #GHashTable use g_hash_table_destroy(). + +A common use-case for hash tables is to store information about a +set of keys, without associating any particular value with each +key. GHashTable optimizes one way of doing so: If you store only +key-value pairs where key == value, then GHashTable does not +allocate memory to store the values, which can be a considerable +space saving, if your set is large. The functions +g_hash_table_add() and g_hash_table_contains() are designed to be +used when using #GHashTable this way. + +#GHashTable is not designed to be statically initialised with keys and +values known at compile time. To build a static hash table, use a tool such +as [gperf](https://www.gnu.org/software/gperf/).</doc> + </docsection> + <docsection name="hmac"> + <doc xml:space="preserve">HMACs should be used when producing a cookie or hash based on data +and a key. Simple mechanisms for using SHA1 and other algorithms to +digest a key and data together are vulnerable to various security +issues. +[HMAC](http://en.wikipedia.org/wiki/HMAC) +uses algorithms like SHA1 in a secure way to produce a digest of a +key and data. + +Both the key and data are arbitrary byte arrays of bytes or characters. + +Support for HMAC Digests has been added in GLib 2.30, and support for SHA-512 +in GLib 2.42. Support for SHA-384 was added in GLib 2.52.</doc> + </docsection> + <function-macro name="hook_append" c:identifier="g_hook_append" introspectable="0"> + <doc xml:space="preserve">Appends a #GHook onto the end of a #GHookList.</doc> + <parameters> + <parameter name="hook_list"> + <doc xml:space="preserve">a #GHookList</doc> + </parameter> + <parameter name="hook"> + <doc xml:space="preserve">the #GHook to add to the end of @hook_list</doc> + </parameter> + </parameters> + </function-macro> + <function name="hook_destroy" c:identifier="g_hook_destroy" moved-to="Hook.destroy"> + <doc xml:space="preserve">Destroys a #GHook, given its ID.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the #GHook was found in the #GHookList and destroyed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="hook_id" transfer-ownership="none"> + <doc xml:space="preserve">a hook ID</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + </parameters> + </function> + <function name="hook_destroy_link" c:identifier="g_hook_destroy_link" moved-to="Hook.destroy_link"> + <doc xml:space="preserve">Removes one #GHook from a #GHookList, marking it +inactive and calling g_hook_unref() on it.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">the #GHook to remove</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + </parameters> + </function> + <function name="hook_free" c:identifier="g_hook_free" moved-to="Hook.free"> + <doc xml:space="preserve">Calls the #GHookList @finalize_hook function if it exists, +and frees the memory allocated for the #GHook.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">the #GHook to free</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + </parameters> + </function> + <function name="hook_insert_before" c:identifier="g_hook_insert_before" moved-to="Hook.insert_before"> + <doc xml:space="preserve">Inserts a #GHook into a #GHookList, before a given #GHook.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="sibling" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the #GHook to insert the new #GHook before</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">the #GHook to insert</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + </parameters> + </function> + <function name="hook_prepend" c:identifier="g_hook_prepend" moved-to="Hook.prepend"> + <doc xml:space="preserve">Prepends a #GHook on the start of a #GHookList.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">the #GHook to add to the start of @hook_list</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + </parameters> + </function> + <function name="hook_unref" c:identifier="g_hook_unref" moved-to="Hook.unref"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="hook_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GHookList</doc> + <type name="HookList" c:type="GHookList*"/> + </parameter> + <parameter name="hook" transfer-ownership="none"> + <doc xml:space="preserve">the #GHook to unref</doc> + <type name="Hook" c:type="GHook*"/> + </parameter> + </parameters> + </function> + <docsection name="hooks"> + <doc xml:space="preserve">The #GHookList, #GHook and their related functions provide support for +lists of hook functions. Functions can be added and removed from the lists, +and the list of hook functions can be invoked.</doc> + </docsection> + <function name="hostname_is_ascii_encoded" c:identifier="g_hostname_is_ascii_encoded" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @hostname contains any ASCII-encoded +segments.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">a hostname</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="hostname_is_ip_address" c:identifier="g_hostname_is_ip_address" version="2.22"> + <doc xml:space="preserve">Tests if @hostname is the string form of an IPv4 or IPv6 address. +(Eg, "192.168.0.1".) + +Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @hostname is an IP address</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">a hostname (or IP address in string form)</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="hostname_is_non_ascii" c:identifier="g_hostname_is_non_ascii" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @hostname contains any non-ASCII characters</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">a hostname</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="hostname_to_ascii" c:identifier="g_hostname_to_ascii" version="2.22"> + <doc xml:space="preserve">Converts @hostname to its canonical ASCII form; an ASCII-only +string containing no uppercase letters and not ending with a +trailing dot.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">an ASCII hostname, which must be freed, + or %NULL if @hostname is in some way invalid.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">a valid UTF-8 or ASCII hostname</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="hostname_to_unicode" c:identifier="g_hostname_to_unicode" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a UTF-8 hostname, which must be freed, + or %NULL if @hostname is in some way invalid.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">a valid UTF-8 or ASCII hostname</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function-macro name="htonl" c:identifier="g_htonl" introspectable="0"> + <doc xml:space="preserve">Converts a 32-bit integer value from host to network byte order.</doc> + <parameters> + <parameter name="val"> + <doc xml:space="preserve">a 32-bit integer value in host byte order</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="htons" c:identifier="g_htons" introspectable="0"> + <doc xml:space="preserve">Converts a 16-bit integer value from host to network byte order.</doc> + <parameters> + <parameter name="val"> + <doc xml:space="preserve">a 16-bit integer value in host byte order</doc> + </parameter> + </parameters> + </function-macro> + <docsection name="i18n"> + <doc xml:space="preserve">GLib doesn't force any particular localization method upon its users. +But since GLib itself is localized using the gettext() mechanism, it seems +natural to offer the de-facto standard gettext() support macros in an +easy-to-use form. + +In order to use these macros in an application, you must include +`<glib/gi18n.h>`. For use in a library, you must include +`<glib/gi18n-lib.h>` +after defining the %GETTEXT_PACKAGE macro suitably for your library: +|[<!-- language="C" --> +#define GETTEXT_PACKAGE "gtk20" +#include <glib/gi18n-lib.h> +]| +For an application, note that you also have to call bindtextdomain(), +bind_textdomain_codeset(), textdomain() and setlocale() early on in your +main() to make gettext() work. For example: +|[<!-- language="C" --> +#include <glib/gi18n.h> +#include <locale.h> + +int +main (int argc, char **argv) +{ + setlocale (LC_ALL, ""); + bindtextdomain (GETTEXT_PACKAGE, DATADIR "/locale"); + bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8"); + textdomain (GETTEXT_PACKAGE); + + // Rest of your application. +} +]| +where `DATADIR` is as typically provided by automake or Meson. + +For a library, you only have to call bindtextdomain() and +bind_textdomain_codeset() in your initialization function. If your library +doesn't have an initialization function, you can call the functions before +the first translated message. + +The +[gettext manual](http://www.gnu.org/software/gettext/manual/gettext.html#Maintainers) +covers details of how to integrate gettext into a project’s build system and +workflow.</doc> + </docsection> + <function name="iconv" c:identifier="g_iconv" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">count of non-reversible conversions, or -1 on error</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="converter" transfer-ownership="none"> + <doc xml:space="preserve">conversion descriptor from g_iconv_open()</doc> + <type name="IConv" c:type="GIConv"/> + </parameter> + <parameter name="inbuf" transfer-ownership="none"> + <doc xml:space="preserve">bytes to convert</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="inbytes_left" transfer-ownership="none"> + <doc xml:space="preserve">inout parameter, bytes remaining to convert in @inbuf</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="outbuf" transfer-ownership="none"> + <doc xml:space="preserve">converted output bytes</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="outbytes_left" transfer-ownership="none"> + <doc xml:space="preserve">inout parameter, bytes available to fill in @outbuf</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </function> + <function name="iconv_open" c:identifier="g_iconv_open" moved-to="IConv.open" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">a "conversion descriptor", or (GIConv)-1 if + opening the converter failed.</doc> + <type name="IConv" c:type="GIConv"/> + </return-value> + <parameters> + <parameter name="to_codeset" transfer-ownership="none"> + <doc xml:space="preserve">destination codeset</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="from_codeset" transfer-ownership="none"> + <doc xml:space="preserve">source codeset</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="idle_add" c:identifier="g_idle_add" shadowed-by="idle_add_full" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ID (greater than 0) of the event source.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="function" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">function to call</doc> + <type name="SourceFunc" c:type="GSourceFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @function.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="idle_add_full" c:identifier="g_idle_add_full" shadows="idle_add"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ID (greater than 0) of the event source.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="priority" transfer-ownership="none"> + <doc xml:space="preserve">the priority of the idle source. Typically this will be in the + range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="function" transfer-ownership="none" scope="notified" closure="2" destroy="3"> + <doc xml:space="preserve">function to call</doc> + <type name="SourceFunc" c:type="GSourceFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">function to call when the idle is removed, or %NULL</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="idle_remove_by_data" c:identifier="g_idle_remove_by_data"> + <doc xml:space="preserve">Removes the idle function with the given data.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if an idle source was found and removed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the idle source's callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="idle_source_new" c:identifier="g_idle_source_new"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the newly-created idle source</doc> + <type name="Source" c:type="GSource*"/> + </return-value> + </function> + <function name="int64_equal" c:identifier="g_int64_equal" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the two keys match.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="v1" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gint64 key</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="v2" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gint64 key to compare with @v1</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="int64_hash" c:identifier="g_int64_hash" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a hash value corresponding to the key.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="v" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gint64 key</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="int_equal" c:identifier="g_int_equal"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the two keys match.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="v1" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gint key</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="v2" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gint key to compare with @v1</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="int_hash" c:identifier="g_int_hash"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a hash value corresponding to the key.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="v" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gint key</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="intern_static_string" c:identifier="g_intern_static_string" version="2.10"> + <doc xml:space="preserve">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++.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a canonical representation for the string</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a static string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="intern_string" c:identifier="g_intern_string" version="2.10"> + <doc xml:space="preserve">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++.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a canonical representation for the string</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="io_add_watch" c:identifier="g_io_add_watch" shadowed-by="io_add_watch_full" introspectable="0"> + <doc xml:space="preserve">Adds the #GIOChannel into the default main loop context +with the default priority.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the event source id</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">the condition to watch for</doc> + <type name="IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="func" transfer-ownership="none" closure="3"> + <doc xml:space="preserve">the function to call when the condition is satisfied</doc> + <type name="IOFunc" c:type="GIOFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to @func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="io_add_watch_full" c:identifier="g_io_add_watch_full" shadows="io_add_watch"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the event source id</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </parameter> + <parameter name="priority" transfer-ownership="none"> + <doc xml:space="preserve">the priority of the #GIOChannel source</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">the condition to watch for</doc> + <type name="IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="func" transfer-ownership="none" scope="notified" closure="4" destroy="5"> + <doc xml:space="preserve">the function to call when the condition is satisfied</doc> + <type name="IOFunc" c:type="GIOFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to @func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">the function to call when the source is removed</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="io_channel_error_from_errno" c:identifier="g_io_channel_error_from_errno" moved-to="IOChannel.error_from_errno"> + <doc xml:space="preserve">Converts an `errno` error number to a #GIOChannelError.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannelError error number, e.g. + %G_IO_CHANNEL_ERROR_INVAL.</doc> + <type name="IOChannelError" c:type="GIOChannelError"/> + </return-value> + <parameters> + <parameter name="en" transfer-ownership="none"> + <doc xml:space="preserve">an `errno` error number, e.g. `EINVAL`</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="io_channel_error_quark" c:identifier="g_io_channel_error_quark" moved-to="IOChannel.error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="io_create_watch" c:identifier="g_io_create_watch"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSource</doc> + <type name="Source" c:type="GSource*"/> + </return-value> + <parameters> + <parameter name="channel" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOChannel to watch</doc> + <type name="IOChannel" c:type="GIOChannel*"/> + </parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">conditions to watch for</doc> + <type name="IOCondition" c:type="GIOCondition"/> + </parameter> + </parameters> + </function> + <docsection name="iochannels"> + <doc xml:space="preserve">The #GIOChannel data type aims to provide a portable method for +using file descriptors, pipes, and sockets, and integrating them +into the [main event loop][glib-The-Main-Event-Loop]. Currently, +full support is available on UNIX platforms, support for Windows +is only partially complete. + +To create a new #GIOChannel on UNIX systems use +g_io_channel_unix_new(). This works for plain file descriptors, +pipes and sockets. Alternatively, a channel can be created for a +file in a system independent manner using g_io_channel_new_file(). + +Once a #GIOChannel has been created, it can be used in a generic +manner with the functions g_io_channel_read_chars(), +g_io_channel_write_chars(), g_io_channel_seek_position(), and +g_io_channel_shutdown(). + +To add a #GIOChannel to the [main event loop][glib-The-Main-Event-Loop], +use g_io_add_watch() or g_io_add_watch_full(). Here you specify which +events you are interested in on the #GIOChannel, and provide a +function to be called whenever these events occur. + +#GIOChannel instances are created with an initial reference count of 1. +g_io_channel_ref() and g_io_channel_unref() can be used to +increment or decrement the reference count respectively. When the +reference count falls to 0, the #GIOChannel is freed. (Though it +isn't closed automatically, unless it was created using +g_io_channel_new_file().) Using g_io_add_watch() or +g_io_add_watch_full() increments a channel's reference count. + +The new functions g_io_channel_read_chars(), +g_io_channel_read_line(), g_io_channel_read_line_string(), +g_io_channel_read_to_end(), g_io_channel_write_chars(), +g_io_channel_seek_position(), and g_io_channel_flush() should not be +mixed with the deprecated functions g_io_channel_read(), +g_io_channel_write(), and g_io_channel_seek() on the same channel.</doc> + </docsection> + <function name="key_file_error_quark" c:identifier="g_key_file_error_quark" moved-to="KeyFile.error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <docsection name="keyfile"> + <doc xml:space="preserve">#GKeyFile lets you parse, edit or create files containing groups of +key-value pairs, which we call "key files" for lack of a better name. +Several freedesktop.org specifications use key files now, e.g the +[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) +and the +[Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec). + +The syntax of key files is described in detail in the +[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec), +here is a quick summary: Key files +consists of groups of key-value pairs, interspersed with comments. + +|[ +# this is just an example +# there can be comments before the first group + +[First Group] + +Name=Key File Example\tthis value shows\nescaping + +# localized strings are stored in multiple key-value pairs +Welcome=Hello +Welcome[de]=Hallo +Welcome[fr_FR]=Bonjour +Welcome[it]=Ciao +Welcome[be@latin]=Hello + +[Another Group] + +Numbers=2;20;-200;0 + +Booleans=true;false;true;true +]| + +Lines beginning with a '#' and blank lines are considered comments. + +Groups are started by a header line containing the group name enclosed +in '[' and ']', and ended implicitly by the start of the next group or +the end of the file. Each key-value pair must be contained in a group. + +Key-value pairs generally have the form `key=value`, with the +exception of localized strings, which have the form +`key[locale]=value`, with a locale identifier of the +form `lang_COUNTRY@MODIFIER` where `COUNTRY` and `MODIFIER` +are optional. +Space before and after the '=' character are ignored. Newline, tab, +carriage return and backslash characters in value are escaped as \n, +\t, \r, and \\\\, respectively. To preserve leading spaces in values, +these can also be escaped as \s. + +Key files can store strings (possibly with localized variants), integers, +booleans and lists of these. Lists are separated by a separator character, +typically ';' or ','. To use the list separator character in a value in +a list, it has to be escaped by prefixing it with a backslash. + +This syntax is obviously inspired by the .ini files commonly met +on Windows, but there are some important differences: + +- .ini files use the ';' character to begin comments, + key files use the '#' character. + +- Key files do not allow for ungrouped keys meaning only + comments can precede the first group. + +- Key files are always encoded in UTF-8. + +- Key and Group names are case-sensitive. For example, a group called + [GROUP] is a different from [group]. + +- .ini files don't have a strongly typed boolean entry type, + they only have GetProfileInt(). In key files, only + true and false (in lower case) are allowed. + +Note that in contrast to the +[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec), +groups in key files may contain the same +key multiple times; the last entry wins. Key files may also contain +multiple groups with the same name; they are merged together. +Another difference is that keys and group names in key files are not +restricted to ASCII characters. + +Here is an example of loading a key file and reading a value: +|[<!-- language="C" --> +g_autoptr(GError) error = NULL; +g_autoptr(GKeyFile) key_file = g_key_file_new (); + +if (!g_key_file_load_from_file (key_file, "key-file.ini", flags, &error)) + { + if (!g_error_matches (error, G_FILE_ERROR, G_FILE_ERROR_NOENT)) + g_warning ("Error loading key file: %s", error->message); + return; + } + +g_autofree gchar *val = g_key_file_get_string (key_file, "Group Name", "SomeKey", &error); +if (val == NULL && + !g_error_matches (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_KEY_NOT_FOUND)) + { + g_warning ("Error finding key in key file: %s", error->message); + return; + } +else if (val == NULL) + { + // Fall back to a default value. + val = g_strdup ("default-value"); + } +]| + +Here is an example of creating and saving a key file: +|[<!-- language="C" --> +g_autoptr(GKeyFile) key_file = g_key_file_new (); +const gchar *val = …; +g_autoptr(GError) error = NULL; + +g_key_file_set_string (key_file, "Group Name", "SomeKey", val); + +// Save as a file. +if (!g_key_file_save_to_file (key_file, "key-file.ini", &error)) + { + g_warning ("Error saving key file: %s", error->message); + return; + } + +// Or store to a GBytes for use elsewhere. +gsize data_len; +g_autofree guint8 *data = (guint8 *) g_key_file_to_data (key_file, &data_len, &error); +if (data == NULL) + { + g_warning ("Error saving key file: %s", error->message); + return; + } +g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len); +]|</doc> + </docsection> + <docsection name="linked_lists_double"> + <doc xml:space="preserve">The #GList structure and its associated functions provide a standard +doubly-linked list data structure. The benefit of this data-structure +is to provide insertion/deletion operations in O(1) complexity where +access/search operations are in O(n). The benefit of #GList over +#GSList (singly linked list) is that the worst case on access/search +operations is divided by two which comes at a cost in space as we need +to retain two pointers in place of one. + +Each element in the list contains a piece of data, together with +pointers which link to the previous and next elements in the list. +Using these pointers it is possible to move through the list in both +directions (unlike the singly-linked [GSList][glib-Singly-Linked-Lists], +which only allows movement through the list in the forward direction). + +The double linked list does not keep track of the number of items +and does not keep track of both the start and end of the list. If +you want fast access to both the start and the end of the list, +and/or the number of items in the list, use a +[GQueue][glib-Double-ended-Queues] instead. + +The data contained in each element can be either integer values, by +using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], +or simply pointers to any type of data. + +List elements are allocated from the [slice allocator][glib-Memory-Slices], +which is more efficient than allocating elements individually. + +Note that most of the #GList functions expect to be passed a pointer +to the first element in the list. The functions which insert +elements return the new start of the list, which may have changed. + +There is no function to create a #GList. %NULL is considered to be +a valid, empty list so you simply set a #GList* to %NULL to initialize +it. + +To add elements, use g_list_append(), g_list_prepend(), +g_list_insert() and g_list_insert_sorted(). + +To visit all elements in the list, use a loop over the list: +|[<!-- language="C" --> +GList *l; +for (l = list; l != NULL; l = l->next) + { + // do something with l->data + } +]| + +To call a function for each element in the list, use g_list_foreach(). + +To loop over the list and modify it (e.g. remove a certain element) +a while loop is more appropriate, for example: +|[<!-- language="C" --> +GList *l = list; +while (l != NULL) + { + GList *next = l->next; + if (should_be_removed (l)) + { + // possibly free l->data + list = g_list_delete_link (list, l); + } + l = next; + } +]| + +To remove elements, use g_list_remove(). + +To navigate in a list, use g_list_first(), g_list_last(), +g_list_next(), g_list_previous(). + +To find elements in the list use g_list_nth(), g_list_nth_data(), +g_list_find() and g_list_find_custom(). + +To find the index of an element use g_list_position() and +g_list_index(). + +To free the entire list, use g_list_free() or g_list_free_full().</doc> + </docsection> + <docsection name="linked_lists_single"> + <doc xml:space="preserve">The #GSList structure and its associated functions provide a +standard singly-linked list data structure. The benefit of this +data-structure is to provide insertion/deletion operations in O(1) +complexity where access/search operations are in O(n). The benefit +of #GSList over #GList (doubly linked list) is that they are lighter +in space as they only need to retain one pointer but it double the +cost of the worst case access/search operations. + +Each element in the list contains a piece of data, together with a +pointer which links to the next element in the list. Using this +pointer it is possible to move through the list in one direction +only (unlike the [double-linked lists][glib-Doubly-Linked-Lists], +which allow movement in both directions). + +The data contained in each element can be either integer values, by +using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], +or simply pointers to any type of data. + +List elements are allocated from the [slice allocator][glib-Memory-Slices], +which is more efficient than allocating elements individually. + +Note that most of the #GSList functions expect to be passed a +pointer to the first element in the list. The functions which insert +elements return the new start of the list, which may have changed. + +There is no function to create a #GSList. %NULL is considered to be +the empty list so you simply set a #GSList* to %NULL. + +To add elements, use g_slist_append(), g_slist_prepend(), +g_slist_insert() and g_slist_insert_sorted(). + +To remove elements, use g_slist_remove(). + +To find elements in the list use g_slist_last(), g_slist_next(), +g_slist_nth(), g_slist_nth_data(), g_slist_find() and +g_slist_find_custom(). + +To find the index of an element use g_slist_position() and +g_slist_index(). + +To call a function for each element in the list use +g_slist_foreach(). + +To free the entire list, use g_slist_free().</doc> + </docsection> + <function-macro name="list_next" c:identifier="g_list_next" introspectable="0"> + <doc xml:space="preserve">A convenience macro to get the next element in a #GList. +Note that it is considered perfectly acceptable to access +@list->next directly.</doc> + <parameters> + <parameter name="list"> + <doc xml:space="preserve">an element in a #GList</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="list_previous" c:identifier="g_list_previous" introspectable="0"> + <doc xml:space="preserve">A convenience macro to get the previous element in a #GList. +Note that it is considered perfectly acceptable to access +@list->prev directly.</doc> + <parameters> + <parameter name="list"> + <doc xml:space="preserve">an element in a #GList</doc> + </parameter> + </parameters> + </function-macro> + <function name="listenv" c:identifier="g_listenv" version="2.8"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + a %NULL-terminated list of strings which must be freed with + g_strfreev().</doc> + <array c:type="gchar**"> + <type name="filename"/> + </array> + </return-value> + </function> + <function name="locale_from_utf8" c:identifier="g_locale_from_utf8" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + A newly-allocated buffer containing the converted string, + or %NULL on an error, and error will be set.</doc> + <array length="3" zero-terminated="0" c:type="gchar*"> + <type name="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="utf8string" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the length of the string, or -1 if the string is + nul-terminated.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">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.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of bytes stored in the output + buffer (not including the terminating nul).</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </function> + <function name="locale_to_utf8" c:identifier="g_locale_to_utf8" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">The converted string, or %NULL on an error.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="opsysstring" transfer-ownership="none"> + <doc xml:space="preserve">a string in the + encoding of the current locale. On Windows + this means the system codepage.</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">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)</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">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.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of bytes stored in the output + buffer (not including the terminating nul).</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </function> + <function name="log" c:identifier="g_log" introspectable="0"> + <doc xml:space="preserve">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()).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="log_domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the log domain, usually #G_LOG_DOMAIN, or %NULL +for the default</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="log_level" transfer-ownership="none"> + <doc xml:space="preserve">the log level, either from #GLogLevelFlags + or a user-defined level</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">the message format. See the printf() documentation</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the parameters to insert into the format string</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="log_default_handler" c:identifier="g_log_default_handler"> + <doc xml:space="preserve">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 + application. + +- `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, unless stderr was requested by +g_log_writer_default_set_use_stderr(). + +This has no effect if structured logging is enabled; see +[Using Structured Logging][using-structured-logging].</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="log_domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the log domain of the message, or %NULL for the +default "" application domain</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="log_level" transfer-ownership="none"> + <doc xml:space="preserve">the level of the message</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="message" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the message</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="unused_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data passed from g_log() which is unused</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="log_remove_handler" c:identifier="g_log_remove_handler"> + <doc xml:space="preserve">Removes the log handler. + +This has no effect if structured logging is enabled; see +[Using Structured Logging][using-structured-logging].</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="log_domain" transfer-ownership="none"> + <doc xml:space="preserve">the log domain</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="handler_id" transfer-ownership="none"> + <doc xml:space="preserve">the id of the handler, which was returned + in g_log_set_handler()</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="log_set_always_fatal" c:identifier="g_log_set_always_fatal"> + <doc xml:space="preserve">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].</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the old fatal mask</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </return-value> + <parameters> + <parameter name="fatal_mask" transfer-ownership="none"> + <doc xml:space="preserve">the mask containing bits set for each level + of error which is to be fatal</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + </parameters> + </function> + <function name="log_set_default_handler" c:identifier="g_log_set_default_handler" version="2.6" introspectable="0"> + <doc xml:space="preserve">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].</doc> + <return-value> + <doc xml:space="preserve">the previous default log handler</doc> + <type name="LogFunc" c:type="GLogFunc"/> + </return-value> + <parameters> + <parameter name="log_func" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">the log handler function</doc> + <type name="LogFunc" c:type="GLogFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data passed to the log handler</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="log_set_fatal_mask" c:identifier="g_log_set_fatal_mask"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the old fatal mask for the log domain</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </return-value> + <parameters> + <parameter name="log_domain" transfer-ownership="none"> + <doc xml:space="preserve">the log domain</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="fatal_mask" transfer-ownership="none"> + <doc xml:space="preserve">the new fatal mask</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + </parameters> + </function> + <function name="log_set_handler" c:identifier="g_log_set_handler" shadowed-by="log_set_handler_full" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the id of the new handler</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="log_domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the log domain, or %NULL for the default "" + application domain</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="log_levels" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="log_func" transfer-ownership="none" closure="3"> + <doc xml:space="preserve">the log handler function</doc> + <type name="LogFunc" c:type="GLogFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data passed to the log handler</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="log_set_handler_full" c:identifier="g_log_set_handler_full" shadows="log_set_handler" version="2.46"> + <doc xml:space="preserve">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].</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the id of the new handler</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="log_domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the log domain, or %NULL for the default "" + application domain</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="log_levels" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="log_func" transfer-ownership="none" scope="notified" closure="3" destroy="4"> + <doc xml:space="preserve">the log handler function</doc> + <type name="LogFunc" c:type="GLogFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data passed to the log handler</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">destroy notify for @user_data, or %NULL</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="log_set_writer_func" c:identifier="g_log_set_writer_func" version="2.50"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="func" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="1" destroy="2"> + <doc xml:space="preserve">log writer function, which must not be %NULL</doc> + <type name="LogWriterFunc" c:type="GLogWriterFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="0"> + <doc xml:space="preserve">user data to pass to @func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="user_data_free" transfer-ownership="none" scope="async" destroy="0"> + <doc xml:space="preserve">function to free @user_data once it’s + finished with, if non-%NULL</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="log_structured" c:identifier="g_log_structured" version="2.50" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="log_domain" transfer-ownership="none"> + <doc xml:space="preserve">log domain, usually %G_LOG_DOMAIN</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="log_level" transfer-ownership="none"> + <doc xml:space="preserve">log level, either from #GLogLevelFlags, or a user-defined + level</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">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</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="log_structured_array" c:identifier="g_log_structured_array" version="2.50"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="log_level" transfer-ownership="none"> + <doc xml:space="preserve">log level, either from #GLogLevelFlags, or a user-defined + level</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="fields" transfer-ownership="none"> + <doc xml:space="preserve">key–value pairs of structured data to add + to the log message</doc> + <array length="2" zero-terminated="0" c:type="const GLogField*"> + <type name="LogField" c:type="GLogField"/> + </array> + </parameter> + <parameter name="n_fields" transfer-ownership="none"> + <doc xml:space="preserve">number of elements in the @fields array</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="log_structured_standard" c:identifier="g_log_structured_standard" introspectable="0"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="log_domain" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="log_level" transfer-ownership="none"> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="file" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="line" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="func" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="message_format" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <varargs/> + </parameter> + </parameters> + </function> + <function name="log_variant" c:identifier="g_log_variant" version="2.50"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="log_domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">log domain, usually %G_LOG_DOMAIN</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="log_level" transfer-ownership="none"> + <doc xml:space="preserve">log level, either from #GLogLevelFlags, or a user-defined + level</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="fields" transfer-ownership="none"> + <doc xml:space="preserve">a dictionary (#GVariant of the type %G_VARIANT_TYPE_VARDICT) +containing the key-value pairs of message data.</doc> + <type name="Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <function name="log_writer_default" c:identifier="g_log_writer_default" version="2.50"> + <doc xml:space="preserve">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_default() uses the mask set by g_log_set_always_fatal() to +determine which messages are fatal. When using a custom writer func instead it is +up to the writer function to determine which log messages are fatal.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise</doc> + <type name="LogWriterOutput" c:type="GLogWriterOutput"/> + </return-value> + <parameters> + <parameter name="log_level" transfer-ownership="none"> + <doc xml:space="preserve">log level, either from #GLogLevelFlags, or a user-defined + level</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="fields" transfer-ownership="none"> + <doc xml:space="preserve">key–value pairs of structured data forming + the log message</doc> + <array length="2" zero-terminated="0" c:type="const GLogField*"> + <type name="LogField" c:type="GLogField"/> + </array> + </parameter> + <parameter name="n_fields" transfer-ownership="none"> + <doc xml:space="preserve">number of elements in the @fields array</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to g_log_set_writer_func()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="log_writer_format_fields" c:identifier="g_log_writer_format_fields" version="2.50"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">string containing the formatted log message, in + the character set of the current locale</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="log_level" transfer-ownership="none"> + <doc xml:space="preserve">log level, either from #GLogLevelFlags, or a user-defined + level</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="fields" transfer-ownership="none"> + <doc xml:space="preserve">key–value pairs of structured data forming + the log message</doc> + <array length="2" zero-terminated="0" c:type="const GLogField*"> + <type name="LogField" c:type="GLogField"/> + </array> + </parameter> + <parameter name="n_fields" transfer-ownership="none"> + <doc xml:space="preserve">number of elements in the @fields array</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="use_color" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to use ANSI color escape sequences when formatting the + message, %FALSE to not</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="log_writer_is_journald" c:identifier="g_log_writer_is_journald" version="2.50"> + <doc xml:space="preserve">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)); +]|</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @output_fd points to the journal, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="output_fd" transfer-ownership="none"> + <doc xml:space="preserve">output file descriptor to check</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="log_writer_journald" c:identifier="g_log_writer_journald" version="2.50"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise</doc> + <type name="LogWriterOutput" c:type="GLogWriterOutput"/> + </return-value> + <parameters> + <parameter name="log_level" transfer-ownership="none"> + <doc xml:space="preserve">log level, either from #GLogLevelFlags, or a user-defined + level</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="fields" transfer-ownership="none"> + <doc xml:space="preserve">key–value pairs of structured data forming + the log message</doc> + <array length="2" zero-terminated="0" c:type="const GLogField*"> + <type name="LogField" c:type="GLogField"/> + </array> + </parameter> + <parameter name="n_fields" transfer-ownership="none"> + <doc xml:space="preserve">number of elements in the @fields array</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to g_log_set_writer_func()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="log_writer_standard_streams" c:identifier="g_log_writer_standard_streams" version="2.50"> + <doc xml:space="preserve">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`, or to `stderr` if requested by +g_log_writer_default_set_use_stderr(); +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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise</doc> + <type name="LogWriterOutput" c:type="GLogWriterOutput"/> + </return-value> + <parameters> + <parameter name="log_level" transfer-ownership="none"> + <doc xml:space="preserve">log level, either from #GLogLevelFlags, or a user-defined + level</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="fields" transfer-ownership="none"> + <doc xml:space="preserve">key–value pairs of structured data forming + the log message</doc> + <array length="2" zero-terminated="0" c:type="const GLogField*"> + <type name="LogField" c:type="GLogField"/> + </array> + </parameter> + <parameter name="n_fields" transfer-ownership="none"> + <doc xml:space="preserve">number of elements in the @fields array</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to g_log_set_writer_func()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="log_writer_supports_color" c:identifier="g_log_writer_supports_color" version="2.50"> + <doc xml:space="preserve">Check whether the given @output_fd file descriptor supports ANSI color +escape sequences. If so, they can safely be used when formatting log +messages.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if ANSI color escapes are supported, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="output_fd" transfer-ownership="none"> + <doc xml:space="preserve">output file descriptor to check</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="logv" c:identifier="g_logv" introspectable="0"> + <doc xml:space="preserve">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()).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="log_domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the log domain, or %NULL for the default "" +application domain</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="log_level" transfer-ownership="none"> + <doc xml:space="preserve">the log level</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">the message format. See the printf() documentation</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">the parameters to insert into the format string</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </function> + <function-macro name="macro__has_attribute" c:identifier="g_macro__has_attribute" introspectable="0"> + <parameters> + <parameter name="x"> + </parameter> + </parameters> + </function-macro> + <function-macro name="macro__has_builtin" c:identifier="g_macro__has_builtin" introspectable="0"> + <parameters> + <parameter name="x"> + </parameter> + </parameters> + </function-macro> + <function-macro name="macro__has_feature" c:identifier="g_macro__has_feature" introspectable="0"> + <parameters> + <parameter name="x"> + </parameter> + </parameters> + </function-macro> + <docsection name="macros"> + <doc xml:space="preserve">These macros provide a few commonly-used features.</doc> + </docsection> + <docsection name="macros_misc"> + <doc xml:space="preserve">These macros provide more specialized features which are not +needed so often by application programmers.</doc> + </docsection> + <docsection name="main"> + <doc xml:space="preserve">The main event loop manages all the available sources of events for +GLib and GTK+ applications. These events can come from any number of +different types of sources such as file descriptors (plain files, +pipes or sockets) and timeouts. New types of event sources can also +be added using g_source_attach(). + +To allow multiple independent sets of sources to be handled in +different threads, each source is associated with a #GMainContext. +A #GMainContext can only be running in a single thread, but +sources can be added to it and removed from it from other threads. All +functions which operate on a #GMainContext or a built-in #GSource are +thread-safe. + +Each event source is assigned a priority. The default priority, +#G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities. +Values greater than 0 denote lower priorities. Events from high priority +sources are always processed before events from lower priority sources. + +Idle functions can also be added, and assigned a priority. These will +be run whenever no events with a higher priority are ready to be processed. + +The #GMainLoop data type represents a main event loop. A GMainLoop is +created with g_main_loop_new(). After adding the initial event sources, +g_main_loop_run() is called. This continuously checks for new events from +each of the event sources and dispatches them. Finally, the processing of +an event from one of the sources leads to a call to g_main_loop_quit() to +exit the main loop, and g_main_loop_run() returns. + +It is possible to create new instances of #GMainLoop recursively. +This is often used in GTK+ applications when showing modal dialog +boxes. Note that event sources are associated with a particular +#GMainContext, and will be checked and dispatched for all main +loops associated with that GMainContext. + +GTK+ contains wrappers of some of these functions, e.g. gtk_main(), +gtk_main_quit() and gtk_events_pending(). + +## Creating new source types + +One of the unusual features of the #GMainLoop functionality +is that new types of event source can be created and used in +addition to the builtin type of event source. A new event source +type is used for handling GDK events. A new source type is created +by "deriving" from the #GSource structure. The derived type of +source is represented by a structure that has the #GSource structure +as a first element, and other elements specific to the new source +type. To create an instance of the new source type, call +g_source_new() passing in the size of the derived structure and +a table of functions. These #GSourceFuncs determine the behavior of +the new source type. + +New source types basically interact with the main context +in two ways. Their prepare function in #GSourceFuncs can set a timeout +to determine the maximum amount of time that the main loop will sleep +before checking the source again. In addition, or as well, the source +can add file descriptors to the set that the main context checks using +g_source_add_poll(). + +## Customizing the main loop iteration + +Single iterations of a #GMainContext can be run with +g_main_context_iteration(). In some cases, more detailed control +of exactly how the details of the main loop work is desired, for +instance, when integrating the #GMainLoop with an external main loop. +In such cases, you can call the component functions of +g_main_context_iteration() directly. These functions are +g_main_context_prepare(), g_main_context_query(), +g_main_context_check() and g_main_context_dispatch(). + +## State of a Main Context # {#mainloop-states} + +The operation of these functions can best be seen in terms +of a state diagram, as shown in this image. + +![](mainloop-states.gif) + +On UNIX, the GLib mainloop is incompatible with fork(). Any program +using the mainloop must either exec() or exit() from the child +without returning to the mainloop. + +## Memory management of sources # {#mainloop-memory-management} + +There are two options for memory management of the user data passed to a +#GSource to be passed to its callback on invocation. This data is provided +in calls to g_timeout_add(), g_timeout_add_full(), g_idle_add(), etc. and +more generally, using g_source_set_callback(). This data is typically an +object which ‘owns’ the timeout or idle callback, such as a widget or a +network protocol implementation. In many cases, it is an error for the +callback to be invoked after this owning object has been destroyed, as that +results in use of freed memory. + +The first, and preferred, option is to store the source ID returned by +functions such as g_timeout_add() or g_source_attach(), and explicitly +remove that source from the main context using g_source_remove() when the +owning object is finalized. This ensures that the callback can only be +invoked while the object is still alive. + +The second option is to hold a strong reference to the object in the +callback, and to release it in the callback’s #GDestroyNotify. This ensures +that the object is kept alive until after the source is finalized, which is +guaranteed to be after it is invoked for the final time. The #GDestroyNotify +is another callback passed to the ‘full’ variants of #GSource functions (for +example, g_timeout_add_full()). It is called when the source is finalized, +and is designed for releasing references like this. + +One important caveat of this second approach is that it will keep the object +alive indefinitely if the main loop is stopped before the #GSource is +invoked, which may be undesirable.</doc> + </docsection> + <function name="main_context_default" c:identifier="g_main_context_default" moved-to="MainContext.default"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the global default main context.</doc> + <type name="MainContext" c:type="GMainContext*"/> + </return-value> + </function> + <function name="main_context_get_thread_default" c:identifier="g_main_context_get_thread_default" moved-to="MainContext.get_thread_default" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the thread-default #GMainContext, or +%NULL if the thread-default context is the global default context.</doc> + <type name="MainContext" c:type="GMainContext*"/> + </return-value> + </function> + <function name="main_context_ref_thread_default" c:identifier="g_main_context_ref_thread_default" moved-to="MainContext.ref_thread_default" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the thread-default #GMainContext. Unref + with g_main_context_unref() when you are done with it.</doc> + <type name="MainContext" c:type="GMainContext*"/> + </return-value> + </function> + <function name="main_current_source" c:identifier="g_main_current_source" version="2.12"> + <doc xml:space="preserve">Returns the currently firing source for this thread.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The currently firing source or %NULL.</doc> + <type name="Source" c:type="GSource*"/> + </return-value> + </function> + <function name="main_depth" c:identifier="g_main_depth"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The main loop recursion level in the current thread</doc> + <type name="gint" c:type="gint"/> + </return-value> + </function> + <function name="malloc" c:identifier="g_malloc"> + <doc xml:space="preserve">Allocates @n_bytes bytes of memory. +If @n_bytes is 0 it returns %NULL.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a pointer to the allocated memory</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="n_bytes" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to allocate</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="malloc0" c:identifier="g_malloc0"> + <doc xml:space="preserve">Allocates @n_bytes bytes of memory, initialized to 0's. +If @n_bytes is 0 it returns %NULL.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a pointer to the allocated memory</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="n_bytes" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to allocate</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="malloc0_n" c:identifier="g_malloc0_n" version="2.24"> + <doc xml:space="preserve">This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes, +but care is taken to detect possible overflow during multiplication.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a pointer to the allocated memory</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="n_blocks" transfer-ownership="none"> + <doc xml:space="preserve">the number of blocks to allocate</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="n_block_bytes" transfer-ownership="none"> + <doc xml:space="preserve">the size of each block in bytes</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="malloc_n" c:identifier="g_malloc_n" version="2.24"> + <doc xml:space="preserve">This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, +but care is taken to detect possible overflow during multiplication.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a pointer to the allocated memory</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="n_blocks" transfer-ownership="none"> + <doc xml:space="preserve">the number of blocks to allocate</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="n_block_bytes" transfer-ownership="none"> + <doc xml:space="preserve">the size of each block in bytes</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <docsection name="markup"> + <doc xml:space="preserve">The "GMarkup" parser is intended to parse a simple markup format +that's a subset of XML. This is a small, efficient, easy-to-use +parser. It should not be used if you expect to interoperate with +other applications generating full-scale XML, and must not be used if you +expect to parse untrusted input. However, it's very +useful for application data files, config files, etc. where you +know your application will be the only one writing the file. +Full-scale XML parsers should be able to parse the subset used by +GMarkup, so you can easily migrate to full-scale XML at a later +time if the need arises. + +GMarkup is not guaranteed to signal an error on all invalid XML; +the parser may accept documents that an XML parser would not. +However, XML documents which are not well-formed (which is a +weaker condition than being valid. See the +[XML specification](http://www.w3.org/TR/REC-xml/) +for definitions of these terms.) are not considered valid GMarkup +documents. + +Simplifications to XML include: + +- Only UTF-8 encoding is allowed + +- No user-defined entities + +- Processing instructions, comments and the doctype declaration + are "passed through" but are not interpreted in any way + +- No DTD or validation + +The markup format does support: + +- Elements + +- Attributes + +- 5 standard entities: &amp; &lt; &gt; &quot; &apos; + +- Character references + +- Sections marked as CDATA</doc> + </docsection> + <function name="markup_collect_attributes" c:identifier="g_markup_collect_attributes" version="2.16" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="element_name" transfer-ownership="none"> + <doc xml:space="preserve">the current tag name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="attribute_names" transfer-ownership="none"> + <doc xml:space="preserve">the attribute names</doc> + <type name="utf8" c:type="const gchar**"/> + </parameter> + <parameter name="attribute_values" transfer-ownership="none"> + <doc xml:space="preserve">the attribute values</doc> + <type name="utf8" c:type="const gchar**"/> + </parameter> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GError or %NULL</doc> + <type name="Error" c:type="GError**"/> + </parameter> + <parameter name="first_type" transfer-ownership="none"> + <doc xml:space="preserve">the #GMarkupCollectType of the first attribute</doc> + <type name="MarkupCollectType" c:type="GMarkupCollectType"/> + </parameter> + <parameter name="first_attr" transfer-ownership="none"> + <doc xml:space="preserve">the name of the first attribute</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">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</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="markup_error_quark" c:identifier="g_markup_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="markup_escape_text" c:identifier="g_markup_escape_text"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string with the escaped text</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="text" transfer-ownership="none"> + <doc xml:space="preserve">some valid UTF-8 text</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">length of @text in bytes, or -1 if the text is nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function name="markup_printf_escaped" c:identifier="g_markup_printf_escaped" version="2.4" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">newly allocated result from formatting + operation. Free with g_free().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">printf() style format string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the arguments to insert in the format string</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="markup_vprintf_escaped" c:identifier="g_markup_vprintf_escaped" version="2.4" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">newly allocated result from formatting + operation. Free with g_free().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">printf() style format string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">variable argument list, similar to vprintf()</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </function> + <function name="mem_is_system_malloc" c:identifier="g_mem_is_system_malloc" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">GLib always uses the system malloc, so this function always +returns %TRUE.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">if %TRUE, malloc() and g_malloc() can be mixed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + </function> + <function name="mem_profile" c:identifier="g_mem_profile" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use other memory profiling tools instead</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </function> + <function name="mem_set_vtable" c:identifier="g_mem_set_vtable" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">This function now does nothing. Use other memory +profiling tools instead</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="vtable" transfer-ownership="none"> + <doc xml:space="preserve">table of memory allocation routines.</doc> + <type name="MemVTable" c:type="GMemVTable*"/> + </parameter> + </parameters> + </function> + <function name="memdup" c:identifier="g_memdup" deprecated="1" deprecated-version="2.68"> + <doc xml:space="preserve">Allocates @byte_size bytes of memory, and copies @byte_size bytes into it +from @mem. If @mem is %NULL it returns %NULL.</doc> + <doc-deprecated xml:space="preserve">Use g_memdup2() instead, as it accepts a #gsize argument + for @byte_size, avoiding the possibility of overflow in a #gsize → #guint + conversion</doc-deprecated> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a pointer to the newly-allocated copy of the memory, or %NULL if @mem + is %NULL.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="mem" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the memory to copy.</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="byte_size" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to copy.</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function-macro name="memmove" c:identifier="g_memmove" introspectable="0" deprecated="1" deprecated-version="2.40"> + <doc xml:space="preserve">Copies a block of memory @len bytes long, from @src to @dest. +The source and destination areas may overlap.</doc> + <doc-deprecated xml:space="preserve">Just use memmove().</doc-deprecated> + <parameters> + <parameter name="dest"> + <doc xml:space="preserve">the destination address to copy the bytes to.</doc> + </parameter> + <parameter name="src"> + <doc xml:space="preserve">the source address to copy the bytes from.</doc> + </parameter> + <parameter name="len"> + <doc xml:space="preserve">the number of bytes to copy.</doc> + </parameter> + </parameters> + </function-macro> + <docsection name="memory"> + <doc xml:space="preserve">These functions provide support for allocating and freeing memory. + +If any call to allocate memory using functions g_new(), g_new0(), g_renew(), +g_malloc(), g_malloc0(), g_malloc0_n(), g_realloc(), and g_realloc_n() +fails, the application is terminated. This also means that there is no +need to check if the call succeeded. On the other hand, the `g_try_...()` family +of functions returns %NULL on failure that can be used as a check +for unsuccessful memory allocation. The application is not terminated +in this case. + +As all GLib functions and data structures use `g_malloc()` internally, unless +otherwise specified, any allocation failure will result in the application +being terminated. + +It's important to match g_malloc() (and wrappers such as g_new()) with +g_free(), g_slice_alloc() (and wrappers such as g_slice_new()) with +g_slice_free(), plain malloc() with free(), and (if you're using C++) +new with delete and new[] with delete[]. Otherwise bad things can happen, +since these allocators may use different memory pools (and new/delete call +constructors and destructors). + +Since GLib 2.46 g_malloc() is hardcoded to always use the system malloc +implementation.</doc> + </docsection> + <docsection name="memory_slices"> + <doc xml:space="preserve">Memory slices provide a space-efficient and multi-processing scalable +way to allocate equal-sized pieces of memory, just like the original +#GMemChunks (from GLib 2.8), while avoiding their excessive +memory-waste, scalability and performance problems. + +To achieve these goals, the slice allocator uses a sophisticated, +layered design that has been inspired by Bonwick's slab allocator +([Bonwick94](http://citeseer.ist.psu.edu/bonwick94slab.html) +Jeff Bonwick, The slab allocator: An object-caching kernel +memory allocator. USENIX 1994, and +[Bonwick01](http://citeseer.ist.psu.edu/bonwick01magazines.html) +Bonwick and Jonathan Adams, Magazines and vmem: Extending the +slab allocator to many cpu's and arbitrary resources. USENIX 2001) + +It uses posix_memalign() to optimize allocations of many equally-sized +chunks, and has per-thread free lists (the so-called magazine layer) +to quickly satisfy allocation requests of already known structure sizes. +This is accompanied by extra caching logic to keep freed memory around +for some time before returning it to the system. Memory that is unused +due to alignment constraints is used for cache colorization (random +distribution of chunk addresses) to improve CPU cache utilization. The +caching layer of the slice allocator adapts itself to high lock contention +to improve scalability. + +The slice allocator can allocate blocks as small as two pointers, and +unlike malloc(), it does not reserve extra space per block. For large block +sizes, g_slice_new() and g_slice_alloc() will automatically delegate to the +system malloc() implementation. For newly written code it is recommended +to use the new `g_slice` API instead of g_malloc() and +friends, as long as objects are not resized during their lifetime and the +object size used at allocation time is still available when freeing. + +Here is an example for using the slice allocator: +|[<!-- language="C" --> +gchar *mem[10000]; +gint i; + +// Allocate 10000 blocks. +for (i = 0; i < 10000; i++) + { + mem[i] = g_slice_alloc (50); + + // Fill in the memory with some junk. + for (j = 0; j < 50; j++) + mem[i][j] = i * j; + } + +// Now free all of the blocks. +for (i = 0; i < 10000; i++) + g_slice_free1 (50, mem[i]); +]| + +And here is an example for using the using the slice allocator +with data structures: +|[<!-- language="C" --> +GRealArray *array; + +// Allocate one block, using the g_slice_new() macro. +array = g_slice_new (GRealArray); + +// We can now use array just like a normal pointer to a structure. +array->data = NULL; +array->len = 0; +array->alloc = 0; +array->zero_terminated = (zero_terminated ? 1 : 0); +array->clear = (clear ? 1 : 0); +array->elt_size = elt_size; + +// We can free the block, so it can be reused. +g_slice_free (GRealArray, array); +]|</doc> + </docsection> + <docsection name="messages"> + <doc xml:space="preserve">These functions provide support for outputting messages. + +The g_return family of macros (g_return_if_fail(), +g_return_val_if_fail(), g_return_if_reached(), +g_return_val_if_reached()) should only be used for programming +errors, a typical use case is checking for invalid parameters at +the beginning of a public function. They should not be used if +you just mean "if (error) return", they should only be used if +you mean "if (bug in program) return". The program behavior is +generally considered undefined after one of these checks fails. +They are not intended for normal control flow, only to give a +perhaps-helpful warning before giving up. + +Structured logging output is supported using g_log_structured(). This differs +from the traditional g_log() API in that log messages are handled as a +collection of key–value pairs representing individual pieces of information, +rather than as a single string containing all the information in an arbitrary +format. + +The convenience macros g_info(), g_message(), g_debug(), g_warning() and g_error() +will use the traditional g_log() API unless you define the symbol +%G_LOG_USE_STRUCTURED before including `glib.h`. But note that even messages +logged through the traditional g_log() API are ultimatively passed to +g_log_structured(), so that all log messages end up in same destination. +If %G_LOG_USE_STRUCTURED is defined, g_test_expect_message() will become +ineffective for the wrapper macros g_warning() and friends (see +[Testing for Messages][testing-for-messages]). + +The support for structured logging was motivated by the following needs (some +of which were supported previously; others weren’t): + * Support for multiple logging levels. + * Structured log support with the ability to add `MESSAGE_ID`s (see + g_log_structured()). + * Moving the responsibility for filtering log messages from the program to + the log viewer — instead of libraries and programs installing log handlers + (with g_log_set_handler()) which filter messages before output, all log + messages are outputted, and the log viewer program (such as `journalctl`) + must filter them. This is based on the idea that bugs are sometimes hard + to reproduce, so it is better to log everything possible and then use + tools to analyse the logs than it is to not be able to reproduce a bug to + get additional log data. Code which uses logging in performance-critical + sections should compile out the g_log_structured() calls in + release builds, and compile them in in debugging builds. + * A single writer function which handles all log messages in a process, from + all libraries and program code; rather than multiple log handlers with + poorly defined interactions between them. This allows a program to easily + change its logging policy by changing the writer function, for example to + log to an additional location or to change what logging output fallbacks + are used. The log writer functions provided by GLib are exposed publicly + so they can be used from programs’ log writers. This allows log writer + policy and implementation to be kept separate. + * If a library wants to add standard information to all of its log messages + (such as library state) or to redact private data (such as passwords or + network credentials), it should use a wrapper function around its + g_log_structured() calls or implement that in the single log writer + function. + * If a program wants to pass context data from a g_log_structured() call to + its log writer function so that, for example, it can use the correct + server connection to submit logs to, that user data can be passed as a + zero-length #GLogField to g_log_structured_array(). + * Color output needed to be supported on the terminal, to make reading + through logs easier. + +## Using Structured Logging ## {#using-structured-logging} + +To use structured logging (rather than the old-style logging), either use +the g_log_structured() and g_log_structured_array() functions; or define +`G_LOG_USE_STRUCTURED` before including any GLib header, and use the +g_message(), g_debug(), g_error() (etc.) macros. + +You do not need to define `G_LOG_USE_STRUCTURED` to use g_log_structured(), +but it is a good idea to avoid confusion. + +## Log Domains ## {#log-domains} + +Log domains may be used to broadly split up the origins of log messages. +Typically, there are one or a few log domains per application or library. +%G_LOG_DOMAIN should be used to define the default log domain for the current +compilation unit — it is typically defined at the top of a source file, or in +the preprocessor flags for a group of source 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`. + +## Debug Message Output ## {#debug-message-output} + +The default log functions (g_log_default_handler() for the old-style API and +g_log_writer_default() for the structured API) both drop debug and +informational messages by default, unless the log domains of those messages +are listed in the `G_MESSAGES_DEBUG` environment variable (or it is set to +`all`). + +It is recommended that custom log writer functions re-use the +`G_MESSAGES_DEBUG` environment variable, rather than inventing a custom one, +so that developers can re-use the same debugging techniques and tools across +projects. Since GLib 2.68, this can be implemented by dropping messages +for which g_log_writer_default_would_drop() returns %TRUE. + +## Testing for Messages ## {#testing-for-messages} + +With the old g_log() API, g_test_expect_message() and +g_test_assert_expected_messages() could be used in simple cases to check +whether some code under test had emitted a given log message. These +functions have been deprecated with the structured logging API, for several +reasons: + * They relied on an internal queue which was too inflexible for many use + cases, where messages might be emitted in several orders, some + messages might not be emitted deterministically, or messages might be + emitted by unrelated log domains. + * They do not support structured log fields. + * Examining the log output of code is a bad approach to testing it, and + while it might be necessary for legacy code which uses g_log(), it should + be avoided for new code using g_log_structured(). + +They will continue to work as before if g_log() is in use (and +%G_LOG_USE_STRUCTURED is not defined). They will do nothing if used with the +structured logging API. + +Examining the log output of code is discouraged: libraries should not emit to +`stderr` during defined behaviour, and hence this should not be tested. If +the log emissions of a library during undefined behaviour need to be tested, +they should be limited to asserting that the library aborts and prints a +suitable error message before aborting. This should be done with +g_test_trap_assert_stderr(). + +If it is really necessary to test the structured log messages emitted by a +particular piece of code – and the code cannot be restructured to be more +suitable to more conventional unit testing – you should write a custom log +writer function (see g_log_set_writer_func()) which appends all log messages +to a queue. When you want to check the log messages, examine and clear the +queue, ignoring irrelevant log messages (for example, from log domains other +than the one under test).</doc> + </docsection> + <docsection name="misc_utils"> + <doc xml:space="preserve">These are portable utility functions.</doc> + </docsection> + <function name="mkdir_with_parents" c:identifier="g_mkdir_with_parents" version="2.8"> + <doc xml:space="preserve">Create a directory if it doesn't already exist. Create intermediate +parent directories as needed, too.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">0 if the directory already exists, or was successfully +created. Returns -1 if an error occurred, with errno set.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="pathname" transfer-ownership="none"> + <doc xml:space="preserve">a pathname in the GLib file name encoding</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve">permissions to use for newly created directories</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="mkdtemp" c:identifier="g_mkdtemp" version="2.30" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="tmpl" transfer-ownership="none"> + <doc xml:space="preserve">template directory name</doc> + <type name="filename" c:type="gchar*"/> + </parameter> + </parameters> + </function> + <function name="mkdtemp_full" c:identifier="g_mkdtemp_full" version="2.30" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="tmpl" transfer-ownership="none"> + <doc xml:space="preserve">template directory name</doc> + <type name="filename" c:type="gchar*"/> + </parameter> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve">permissions to create the temporary directory with</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="mkstemp" c:identifier="g_mkstemp" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="tmpl" transfer-ownership="none"> + <doc xml:space="preserve">template filename</doc> + <type name="filename" c:type="gchar*"/> + </parameter> + </parameters> + </function> + <function name="mkstemp_full" c:identifier="g_mkstemp_full" version="2.22" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="tmpl" transfer-ownership="none"> + <doc xml:space="preserve">template filename</doc> + <type name="filename" c:type="gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags to pass to an open() call in addition to O_EXCL + and O_CREAT, which are passed automatically</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve">permissions to create the temporary file with</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function-macro name="new" c:identifier="g_new" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="struct_type"> + <doc xml:space="preserve">the type of the elements to allocate</doc> + </parameter> + <parameter name="n_structs"> + <doc xml:space="preserve">the number of elements to allocate</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="new0" c:identifier="g_new0" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="struct_type"> + <doc xml:space="preserve">the type of the elements to allocate.</doc> + </parameter> + <parameter name="n_structs"> + <doc xml:space="preserve">the number of elements to allocate.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="newa" c:identifier="g_newa" introspectable="0"> + <doc xml:space="preserve">Wraps g_alloca() in a more typesafe manner.</doc> + <parameters> + <parameter name="struct_type"> + <doc xml:space="preserve">Type of memory chunks to be allocated</doc> + </parameter> + <parameter name="n_structs"> + <doc xml:space="preserve">Number of chunks to be allocated</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="node_append" c:identifier="g_node_append" introspectable="0"> + <doc xml:space="preserve">Inserts a #GNode as the last child of the given parent.</doc> + <parameters> + <parameter name="parent"> + <doc xml:space="preserve">the #GNode to place the new #GNode under</doc> + </parameter> + <parameter name="node"> + <doc xml:space="preserve">the #GNode to insert</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="node_append_data" c:identifier="g_node_append_data" introspectable="0"> + <doc xml:space="preserve">Inserts a new #GNode as the last child of the given parent.</doc> + <parameters> + <parameter name="parent"> + <doc xml:space="preserve">the #GNode to place the new #GNode under</doc> + </parameter> + <parameter name="data"> + <doc xml:space="preserve">the data for the new #GNode</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="node_first_child" c:identifier="g_node_first_child" introspectable="0"> + <doc xml:space="preserve">Gets the first child of a #GNode.</doc> + <parameters> + <parameter name="node"> + <doc xml:space="preserve">a #GNode</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="node_insert_data" c:identifier="g_node_insert_data" introspectable="0"> + <doc xml:space="preserve">Inserts a new #GNode at the given position.</doc> + <parameters> + <parameter name="parent"> + <doc xml:space="preserve">the #GNode to place the new #GNode under</doc> + </parameter> + <parameter name="position"> + <doc xml:space="preserve">the position to place the new #GNode at. If position is -1, + the new #GNode is inserted as the last child of @parent</doc> + </parameter> + <parameter name="data"> + <doc xml:space="preserve">the data for the new #GNode</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="node_insert_data_after" c:identifier="g_node_insert_data_after" introspectable="0"> + <doc xml:space="preserve">Inserts a new #GNode after the given sibling.</doc> + <parameters> + <parameter name="parent"> + <doc xml:space="preserve">the #GNode to place the new #GNode under</doc> + </parameter> + <parameter name="sibling"> + <doc xml:space="preserve">the sibling #GNode to place the new #GNode after</doc> + </parameter> + <parameter name="data"> + <doc xml:space="preserve">the data for the new #GNode</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="node_insert_data_before" c:identifier="g_node_insert_data_before" introspectable="0"> + <doc xml:space="preserve">Inserts a new #GNode before the given sibling.</doc> + <parameters> + <parameter name="parent"> + <doc xml:space="preserve">the #GNode to place the new #GNode under</doc> + </parameter> + <parameter name="sibling"> + <doc xml:space="preserve">the sibling #GNode to place the new #GNode before</doc> + </parameter> + <parameter name="data"> + <doc xml:space="preserve">the data for the new #GNode</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="node_next_sibling" c:identifier="g_node_next_sibling" introspectable="0"> + <doc xml:space="preserve">Gets the next sibling of a #GNode.</doc> + <parameters> + <parameter name="node"> + <doc xml:space="preserve">a #GNode</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="node_prepend_data" c:identifier="g_node_prepend_data" introspectable="0"> + <doc xml:space="preserve">Inserts a new #GNode as the first child of the given parent.</doc> + <parameters> + <parameter name="parent"> + <doc xml:space="preserve">the #GNode to place the new #GNode under</doc> + </parameter> + <parameter name="data"> + <doc xml:space="preserve">the data for the new #GNode</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="node_prev_sibling" c:identifier="g_node_prev_sibling" introspectable="0"> + <doc xml:space="preserve">Gets the previous sibling of a #GNode.</doc> + <parameters> + <parameter name="node"> + <doc xml:space="preserve">a #GNode</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="ntohl" c:identifier="g_ntohl" introspectable="0"> + <doc xml:space="preserve">Converts a 32-bit integer value from network to host byte order.</doc> + <parameters> + <parameter name="val"> + <doc xml:space="preserve">a 32-bit integer value in network byte order</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="ntohs" c:identifier="g_ntohs" introspectable="0"> + <doc xml:space="preserve">Converts a 16-bit integer value from network to host byte order.</doc> + <parameters> + <parameter name="val"> + <doc xml:space="preserve">a 16-bit integer value in network byte order</doc> + </parameter> + </parameters> + </function-macro> + <function name="nullify_pointer" c:identifier="g_nullify_pointer"> + <doc xml:space="preserve">Set the pointer at the specified location to %NULL.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="nullify_location" transfer-ownership="none"> + <doc xml:space="preserve">the memory address of the pointer.</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + </parameters> + </function> + <function name="number_parser_error_quark" c:identifier="g_number_parser_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <docsection name="numerical"> + <doc xml:space="preserve">GLib offers mathematical constants such as #G_PI for the value of pi; +many platforms have these in the C library, but some don't, the GLib +versions always exist. + +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. See +[IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float) +for more information about IEEE number formats.</doc> + </docsection> + <function name="on_error_query" c:identifier="g_on_error_query"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="prg_name" transfer-ownership="none"> + <doc xml:space="preserve">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)</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="on_error_stack_trace" c:identifier="g_on_error_stack_trace"> + <doc xml:space="preserve">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)).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="prg_name" transfer-ownership="none"> + <doc xml:space="preserve">the program name, needed by gdb for the "[S]tack trace" + option</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function-macro name="once" c:identifier="g_once" version="2.4" introspectable="0"> + <doc xml:space="preserve">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; + } +]|</doc> + <parameters> + <parameter name="once"> + <doc xml:space="preserve">a #GOnce structure</doc> + </parameter> + <parameter name="func"> + <doc xml:space="preserve">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().</doc> + </parameter> + <parameter name="arg"> + <doc xml:space="preserve">data to be passed to @func</doc> + </parameter> + </parameters> + </function-macro> + <function name="once_init_enter" c:identifier="g_once_init_enter" moved-to="Once.init_enter" version="2.14"> + <doc xml:space="preserve">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 +]| + +While @location has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the initialization section should be entered, + %FALSE and blocks otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="location" transfer-ownership="none"> + <doc xml:space="preserve">location of a static initializable variable + containing 0</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + </parameters> + </function> + <function name="once_init_leave" c:identifier="g_once_init_leave" moved-to="Once.init_leave" version="2.14"> + <doc xml:space="preserve">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. + +While @location has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="location" transfer-ownership="none"> + <doc xml:space="preserve">location of a static initializable variable + containing 0</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">new non-0 value for *@value_location</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <docsection name="option"> + <doc xml:space="preserve">The GOption commandline parser is intended to be a simpler replacement +for the popt library. It supports short and long commandline options, +as shown in the following example: + +`testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2` + +The example demonstrates a number of features of the GOption +commandline parser: + +- Options can be single letters, prefixed by a single dash. + +- Multiple short options can be grouped behind a single dash. + +- Long options are prefixed by two consecutive dashes. + +- Options can have an extra argument, which can be a number, a string or + a filename. For long options, the extra argument can be appended with + an equals sign after the option name, which is useful if the extra + argument starts with a dash, which would otherwise cause it to be + interpreted as another option. + +- Non-option arguments are returned to the application as rest arguments. + +- An argument consisting solely of two dashes turns off further parsing, + any remaining arguments (even those starting with a dash) are returned + to the application as rest arguments. + +Another important feature of GOption is that it can automatically +generate nicely formatted help output. Unless it is explicitly turned +off with g_option_context_set_help_enabled(), GOption will recognize +the `--help`, `-?`, `--help-all` and `--help-groupname` options +(where `groupname` is the name of a #GOptionGroup) and write a text +similar to the one shown in the following example to stdout. + +|[ +Usage: + testtreemodel [OPTION...] - test tree model performance + +Help Options: + -h, --help Show help options + --help-all Show all help options + --help-gtk Show GTK+ Options + +Application Options: + -r, --repeats=N Average over N repetitions + -m, --max-size=M Test up to 2^M items + --display=DISPLAY X display to use + -v, --verbose Be verbose + -b, --beep Beep when done + --rand Randomize the data +]| + +GOption groups options in #GOptionGroups, which makes it easy to +incorporate options from multiple sources. The intended use for this is +to let applications collect option groups from the libraries it uses, +add them to their #GOptionContext, and parse all options by a single call +to g_option_context_parse(). See gtk_get_option_group() for an example. + +If an option is declared to be of type string or filename, GOption takes +care of converting it to the right encoding; strings are returned in +UTF-8, filenames are returned in the GLib filename encoding. Note that +this only works if setlocale() has been called before +g_option_context_parse(). + +Here is a complete example of setting up GOption to parse the example +commandline above and produce the example help output. +|[<!-- language="C" --> +static gint repeats = 2; +static gint max_size = 8; +static gboolean verbose = FALSE; +static gboolean beep = FALSE; +static gboolean randomize = FALSE; + +static GOptionEntry entries[] = +{ + { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" }, + { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" }, + { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL }, + { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL }, + { "rand", 0, 0, G_OPTION_ARG_NONE, &randomize, "Randomize the data", NULL }, + { NULL } +}; + +int +main (int argc, char *argv[]) +{ + GError *error = NULL; + GOptionContext *context; + + context = g_option_context_new ("- test tree model performance"); + g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE); + g_option_context_add_group (context, gtk_get_option_group (TRUE)); + if (!g_option_context_parse (context, &argc, &argv, &error)) + { + g_print ("option parsing failed: %s\n", error->message); + exit (1); + } + + ... + +} +]| + +On UNIX systems, the argv that is passed to main() has no particular +encoding, even to the extent that different parts of it may have +different encodings. In general, normal arguments and flags will be +in the current locale and filenames should be considered to be opaque +byte strings. Proper use of %G_OPTION_ARG_FILENAME vs +%G_OPTION_ARG_STRING is therefore important. + +Note that on Windows, filenames do have an encoding, but using +#GOptionContext with the argv as passed to main() will result in a +program that can only accept commandline arguments with characters +from the system codepage. This can cause problems when attempting to +deal with filenames containing Unicode characters that fall outside +of the codepage. + +A solution to this is to use g_win32_get_command_line() and +g_option_context_parse_strv() which will properly handle full Unicode +filenames. If you are using #GApplication, this is done +automatically for you. + +The following example shows how you can use #GOptionContext directly +in order to correctly deal with Unicode filenames on Windows: + +|[<!-- language="C" --> +int +main (int argc, char **argv) +{ + GError *error = NULL; + GOptionContext *context; + gchar **args; + +#ifdef G_OS_WIN32 + args = g_win32_get_command_line (); +#else + args = g_strdupv (argv); +#endif + + // set up context + + if (!g_option_context_parse_strv (context, &args, &error)) + { + // error happened + } + + ... + + g_strfreev (args); + + ... +} +]|</doc> + </docsection> + <function name="option_error_quark" c:identifier="g_option_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="parse_debug_string" c:identifier="g_parse_debug_string"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the combined set of bit flags.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a list of debug options separated by colons, spaces, or +commas, or %NULL.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="keys" transfer-ownership="none"> + <doc xml:space="preserve">pointer to an array of #GDebugKey which associate + strings with bit flags.</doc> + <array length="2" zero-terminated="0" c:type="const GDebugKey*"> + <type name="DebugKey" c:type="GDebugKey"/> + </array> + </parameter> + <parameter name="nkeys" transfer-ownership="none"> + <doc xml:space="preserve">the number of #GDebugKeys in the array.</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="path_get_basename" c:identifier="g_path_get_basename"> + <doc xml:space="preserve">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 ".".</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string containing the last + component of the filename</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="file_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the file</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="path_get_dirname" c:identifier="g_path_get_dirname"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the directory components of the file</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="file_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the file</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="path_is_absolute" c:identifier="g_path_is_absolute"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @file_name is absolute</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file_name" transfer-ownership="none"> + <doc xml:space="preserve">a file name</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="path_skip_root" c:identifier="g_path_skip_root"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a pointer into @file_name after the + root component</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="file_name" transfer-ownership="none"> + <doc xml:space="preserve">a file name</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="pattern_match" c:identifier="g_pattern_match"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @string matches @pspec</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a #GPatternSpec</doc> + <type name="PatternSpec" c:type="GPatternSpec*"/> + </parameter> + <parameter name="string_length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @string (in bytes, i.e. strlen(), + not g_utf8_strlen())</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the UTF-8 encoded string to match</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="string_reversed" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the reverse of @string or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="pattern_match_simple" c:identifier="g_pattern_match_simple"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @string matches @pspec</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="pattern" transfer-ownership="none"> + <doc xml:space="preserve">the UTF-8 encoded pattern</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the UTF-8 encoded string to match</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="pattern_match_string" c:identifier="g_pattern_match_string"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @string matches @pspec</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a #GPatternSpec</doc> + <type name="PatternSpec" c:type="GPatternSpec*"/> + </parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the UTF-8 encoded string to match</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <docsection name="patterns"> + <doc xml:space="preserve">The g_pattern_match* functions match a string +against a pattern containing '*' and '?' wildcards with similar +semantics as the standard glob() function: '*' matches an arbitrary, +possibly empty, string, '?' matches an arbitrary character. + +Note that in contrast to glob(), the '/' character can be matched by +the wildcards, there are no '[...]' character ranges and '*' and '?' +can not be escaped to include them literally in a pattern. + +When multiple strings must be matched against the same pattern, it +is better to compile the pattern to a #GPatternSpec using +g_pattern_spec_new() and use g_pattern_match_string() instead of +g_pattern_match_simple(). This avoids the overhead of repeated +pattern compilation.</doc> + </docsection> + <function name="pointer_bit_lock" c:identifier="g_pointer_bit_lock" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gpointer-sized value</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + <parameter name="lock_bit" transfer-ownership="none"> + <doc xml:space="preserve">a bit value between 0 and 31</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="pointer_bit_trylock" c:identifier="g_pointer_bit_trylock" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the lock was acquired</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gpointer-sized value</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + <parameter name="lock_bit" transfer-ownership="none"> + <doc xml:space="preserve">a bit value between 0 and 31</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="pointer_bit_unlock" c:identifier="g_pointer_bit_unlock" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #gpointer-sized value</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + <parameter name="lock_bit" transfer-ownership="none"> + <doc xml:space="preserve">a bit value between 0 and 31</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="poll" c:identifier="g_poll" version="2.20"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="fds" transfer-ownership="none"> + <doc xml:space="preserve">file descriptors to poll</doc> + <type name="PollFD" c:type="GPollFD*"/> + </parameter> + <parameter name="nfds" transfer-ownership="none"> + <doc xml:space="preserve">the number of file descriptors in @fds</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="timeout" transfer-ownership="none"> + <doc xml:space="preserve">amount of time to wait, in milliseconds, or -1 to wait forever</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="prefix_error" c:identifier="g_prefix_error" version="2.16" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="err" direction="inout" caller-allocates="0" transfer-ownership="full" nullable="1" allow-none="1" optional="1"> + <doc xml:space="preserve">a return location for a #GError</doc> + <type name="Error" c:type="GError**"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">printf()-style format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">arguments to @format</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="print" c:identifier="g_print" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">the message format. See the printf() documentation</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the parameters to insert into the format string</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="printerr" c:identifier="g_printerr" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">the message format. See the printf() documentation</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the parameters to insert into the format string</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="printf" c:identifier="g_printf" version="2.2" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes printed.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a standard printf() format string, but notice + [string precision pitfalls][string-precision]</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the arguments to insert in the output.</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="printf_string_upper_bound" c:identifier="g_printf_string_upper_bound" introspectable="0"> + <doc xml:space="preserve">Calculates the maximum space needed to store the output +of the sprintf() function.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the maximum space needed to store the formatted string</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">the format string. See the printf() documentation</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">the parameters to be inserted into the format string</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </function> + <function name="propagate_error" c:identifier="g_propagate_error"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="dest" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">error return location</doc> + <type name="Error" c:type="GError**"/> + </parameter> + <parameter name="src" transfer-ownership="full"> + <doc xml:space="preserve">error to move into the return location</doc> + <type name="Error" c:type="GError*"/> + </parameter> + </parameters> + </function> + <function name="propagate_prefixed_error" c:identifier="g_propagate_prefixed_error" version="2.16" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="dest" transfer-ownership="none"> + <doc xml:space="preserve">error return location</doc> + <type name="Error" c:type="GError**"/> + </parameter> + <parameter name="src" transfer-ownership="none"> + <doc xml:space="preserve">error to move into the return location</doc> + <type name="Error" c:type="GError*"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">printf()-style format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">arguments to @format</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="ptr_array_find" c:identifier="g_ptr_array_find" moved-to="PtrArray.find" version="2.54" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @needle is one of the elements of @haystack</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="haystack" transfer-ownership="none"> + <doc xml:space="preserve">pointer array to be searched</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="needle" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">pointer to look for</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="index_" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the index of + the element, if found</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </function> + <function name="ptr_array_find_with_equal_func" c:identifier="g_ptr_array_find_with_equal_func" moved-to="PtrArray.find_with_equal_func" version="2.54" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @needle is one of the elements of @haystack</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="haystack" transfer-ownership="none"> + <doc xml:space="preserve">pointer array to be searched</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="needle" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">pointer to look for</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="equal_func" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the function to call for each element, which should + return %TRUE when the desired element is found; or %NULL to use pointer + equality</doc> + <type name="EqualFunc" c:type="GEqualFunc"/> + </parameter> + <parameter name="index_" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the index of + the element, if found</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </function> + <function-macro name="ptr_array_index" c:identifier="g_ptr_array_index" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="array"> + <doc xml:space="preserve">a #GPtrArray</doc> + </parameter> + <parameter name="index_"> + <doc xml:space="preserve">the index of the pointer to return</doc> + </parameter> + </parameters> + </function-macro> + <function name="qsort_with_data" c:identifier="g_qsort_with_data" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="pbase" transfer-ownership="none"> + <doc xml:space="preserve">start of array to sort</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="total_elems" transfer-ownership="none"> + <doc xml:space="preserve">elements in the array</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">size of each element</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="compare_func" transfer-ownership="none" closure="4"> + <doc xml:space="preserve">function to compare elements</doc> + <type name="CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @compare_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="quark_from_static_string" c:identifier="g_quark_from_static_string"> + <doc xml:space="preserve">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++.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GQuark identifying the string, or 0 if @string is %NULL</doc> + <type name="Quark" c:type="GQuark"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="quark_from_string" c:identifier="g_quark_from_string"> + <doc xml:space="preserve">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++.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GQuark identifying the string, or 0 if @string is %NULL</doc> + <type name="Quark" c:type="GQuark"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="quark_to_string" c:identifier="g_quark_to_string"> + <doc xml:space="preserve">Gets the string associated with the given #GQuark.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the string associated with the #GQuark</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="quark" transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark.</doc> + <type name="Quark" c:type="GQuark"/> + </parameter> + </parameters> + </function> + <function name="quark_try_string" c:identifier="g_quark_try_string"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GQuark associated with the string, or 0 if @string is + %NULL or there is no #GQuark associated with it</doc> + <type name="Quark" c:type="GQuark"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <docsection name="quarks"> + <doc xml:space="preserve">Quarks are associations between strings and integer identifiers. +Given either the string or the #GQuark identifier it is possible to +retrieve the other. + +Quarks are used for both [datasets][glib-Datasets] and +[keyed data lists][glib-Keyed-Data-Lists]. + +To create a new quark from a string, use g_quark_from_string() or +g_quark_from_static_string(). + +To find the string corresponding to a given #GQuark, use +g_quark_to_string(). + +To find the #GQuark corresponding to a given string, use +g_quark_try_string(). + +Another use for the string pool maintained for the quark functions +is string interning, using g_intern_string() or +g_intern_static_string(). An interned string is a canonical +representation for a string. One important advantage of interned +strings is that they can be compared for equality by a simple +pointer comparison, rather than using strcmp().</doc> + </docsection> + <docsection name="queue"> + <doc xml:space="preserve">The #GQueue structure and its associated functions provide a standard +queue data structure. Internally, GQueue uses the same data structure +as #GList to store elements with the same complexity over +insertion/deletion (O(1)) and access/search (O(n)) operations. + +The data contained in each element can be either integer values, by +using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], +or simply pointers to any type of data. + +As with all other GLib data structures, #GQueue is not thread-safe. +For a thread-safe queue, use #GAsyncQueue. + +To create a new GQueue, use g_queue_new(). + +To initialize a statically-allocated GQueue, use #G_QUEUE_INIT or +g_queue_init(). + +To add elements, use g_queue_push_head(), g_queue_push_head_link(), +g_queue_push_tail() and g_queue_push_tail_link(). + +To remove elements, use g_queue_pop_head() and g_queue_pop_tail(). + +To free the entire queue, use g_queue_free().</doc> + </docsection> + <function-macro name="rand_boolean" c:identifier="g_rand_boolean" introspectable="0"> + <doc xml:space="preserve">Returns a random #gboolean from @rand_. +This corresponds to an unbiased coin toss.</doc> + <parameters> + <parameter name="rand_"> + <doc xml:space="preserve">a #GRand</doc> + </parameter> + </parameters> + </function-macro> + <function name="random_double" c:identifier="g_random_double"> + <doc xml:space="preserve">Returns a random #gdouble equally distributed over the range [0..1).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a random number</doc> + <type name="gdouble" c:type="gdouble"/> + </return-value> + </function> + <function name="random_double_range" c:identifier="g_random_double_range"> + <doc xml:space="preserve">Returns a random #gdouble equally distributed over the range +[@begin..@end).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a random number</doc> + <type name="gdouble" c:type="gdouble"/> + </return-value> + <parameters> + <parameter name="begin" transfer-ownership="none"> + <doc xml:space="preserve">lower closed bound of the interval</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + <parameter name="end" transfer-ownership="none"> + <doc xml:space="preserve">upper open bound of the interval</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + </parameters> + </function> + <function name="random_int" c:identifier="g_random_int"> + <doc xml:space="preserve">Return a random #guint32 equally distributed over the range +[0..2^32-1].</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a random number</doc> + <type name="guint32" c:type="guint32"/> + </return-value> + </function> + <function name="random_int_range" c:identifier="g_random_int_range"> + <doc xml:space="preserve">Returns a random #gint32 equally distributed over the range +[@begin..@end-1].</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a random number</doc> + <type name="gint32" c:type="gint32"/> + </return-value> + <parameters> + <parameter name="begin" transfer-ownership="none"> + <doc xml:space="preserve">lower closed bound of the interval</doc> + <type name="gint32" c:type="gint32"/> + </parameter> + <parameter name="end" transfer-ownership="none"> + <doc xml:space="preserve">upper open bound of the interval</doc> + <type name="gint32" c:type="gint32"/> + </parameter> + </parameters> + </function> + <docsection name="random_numbers"> + <doc xml:space="preserve">The following functions allow you to use a portable, fast and good +pseudo-random number generator (PRNG). + +Do not use this API for cryptographic purposes such as key +generation, nonces, salts or one-time pads. + +This PRNG is suitable for non-cryptographic use such as in games +(shuffling a card deck, generating levels), generating data for +a test suite, etc. If you need random data for cryptographic +purposes, it is recommended to use platform-specific APIs such +as `/dev/random` on UNIX, or CryptGenRandom() on Windows. + +GRand uses the Mersenne Twister PRNG, which was originally +developed by Makoto Matsumoto and Takuji Nishimura. Further +information can be found at +[this page](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html). + +If you just need a random number, you simply call the g_random_* +functions, which will create a globally used #GRand and use the +according g_rand_* functions internally. Whenever you need a +stream of reproducible random numbers, you better create a +#GRand yourself and use the g_rand_* functions directly, which +will also be slightly faster. Initializing a #GRand with a +certain seed will produce exactly the same series of random +numbers on all platforms. This can thus be used as a seed for +e.g. games. + +The g_rand*_range functions will return high quality equally +distributed random numbers, whereas for example the +`(g_random_int()%max)` approach often +doesn't yield equally distributed numbers. + +GLib changed the seeding algorithm for the pseudo-random number +generator Mersenne Twister, as used by #GRand. This was necessary, +because some seeds would yield very bad pseudo-random streams. +Also the pseudo-random integers generated by g_rand*_int_range() +will have a slightly better equal distribution with the new +version of GLib. + +The original seeding and generation algorithms, as found in +GLib 2.0.x, can be used instead of the new ones by setting the +environment variable `G_RANDOM_VERSION` to the value of '2.0'. +Use the GLib-2.0 algorithms only if you have sequences of numbers +generated with Glib-2.0 that you need to reproduce exactly.</doc> + </docsection> + <function name="random_set_seed" c:identifier="g_random_set_seed"> + <doc xml:space="preserve">Sets the seed for the global random number generator, which is used +by the g_random_* functions, to @seed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="seed" transfer-ownership="none"> + <doc xml:space="preserve">a value to reinitialize the global random number generator</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + </parameters> + </function> + <function name="rc_box_acquire" c:identifier="g_rc_box_acquire" version="2.58"> + <doc xml:space="preserve">Acquires a reference on the data pointed by @mem_block.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to the data, + with its reference count increased</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="mem_block" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to reference counted data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="rc_box_alloc" c:identifier="g_rc_box_alloc" version="2.58"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to the allocated memory</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="block_size" transfer-ownership="none"> + <doc xml:space="preserve">the size of the allocation, must be greater than 0</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="rc_box_alloc0" c:identifier="g_rc_box_alloc0" version="2.58"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to the allocated memory</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="block_size" transfer-ownership="none"> + <doc xml:space="preserve">the size of the allocation, must be greater than 0</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="rc_box_dup" c:identifier="g_rc_box_dup" version="2.58"> + <doc xml:space="preserve">Allocates a new block of data with reference counting +semantics, and copies @block_size bytes of @mem_block +into it.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to the allocated + memory</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="block_size" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to copy, must be greater than 0</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="mem_block" transfer-ownership="none"> + <doc xml:space="preserve">the memory to copy</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="rc_box_get_size" c:identifier="g_rc_box_get_size" version="2.58"> + <doc xml:space="preserve">Retrieves the size of the reference counted data pointed by @mem_block.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the size of the data, in bytes</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="mem_block" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to reference counted data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function-macro name="rc_box_new" c:identifier="g_rc_box_new" version="2.58" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">the type to allocate, typically a structure name</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="rc_box_new0" c:identifier="g_rc_box_new0" version="2.58" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">the type to allocate, typically a structure name</doc> + </parameter> + </parameters> + </function-macro> + <function name="rc_box_release" c:identifier="g_rc_box_release" version="2.58"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mem_block" transfer-ownership="full"> + <doc xml:space="preserve">a pointer to reference counted data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="rc_box_release_full" c:identifier="g_rc_box_release_full" version="2.58"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mem_block" transfer-ownership="full"> + <doc xml:space="preserve">a pointer to reference counted data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="clear_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">a function to call when clearing the data</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <docsection name="rcbox"> + <doc xml:space="preserve">A "reference counted box", or "RcBox", is an opaque wrapper data type +that is guaranteed to be as big as the size of a given data type, and +which augments the given data type with reference counting semantics +for its memory management. + +RcBox is useful if you have a plain old data type, like a structure +typically placed on the stack, and you wish to provide additional API +to use it on the heap; or if you want to implement a new type to be +passed around by reference without necessarily implementing copy/free +semantics or your own reference counting. + +The typical use is: + +|[<!-- language="C" --> +typedef struct { + char *name; + char *address; + char *city; + char *state; + int age; +} Person; + +Person * +person_new (void) +{ + return g_rc_box_new0 (Person); +} +]| + +Every time you wish to acquire a reference on the memory, you should +call g_rc_box_acquire(); similarly, when you wish to release a reference +you should call g_rc_box_release(): + +|[<!-- language="C" --> +// Add a Person to the Database; the Database acquires ownership +// of the Person instance +void +add_person_to_database (Database *db, Person *p) +{ + db->persons = g_list_prepend (db->persons, g_rc_box_acquire (p)); +} + +// Removes a Person from the Database; the reference acquired by +// add_person_to_database() is released here +void +remove_person_from_database (Database *db, Person *p) +{ + db->persons = g_list_remove (db->persons, p); + g_rc_box_release (p); +} +]| + +If you have additional memory allocated inside the structure, you can +use g_rc_box_release_full(), which takes a function pointer, which +will be called if the reference released was the last: + +|[<!-- language="C" --> +void +person_clear (Person *p) +{ + g_free (p->name); + g_free (p->address); + g_free (p->city); + g_free (p->state); +} + +void +remove_person_from_database (Database *db, Person *p) +{ + db->persons = g_list_remove (db->persons, p); + g_rc_box_release_full (p, (GDestroyNotify) person_clear); +} +]| + +If you wish to transfer the ownership of a reference counted data +type without increasing the reference count, you can use g_steal_pointer(): + +|[<!-- language="C" --> + Person *p = g_rc_box_new (Person); + + // fill_person_details() is defined elsewhere + fill_person_details (p); + + // add_person_to_database_no_ref() is defined elsewhere; it adds + // a Person to the Database without taking a reference + add_person_to_database_no_ref (db, g_steal_pointer (&p)); +]| + +## Thread safety + +The reference counting operations on data allocated using g_rc_box_alloc(), +g_rc_box_new(), and g_rc_box_dup() are not thread safe; it is your code's +responsibility to ensure that references are acquired are released on the +same thread. + +If you need thread safe reference counting, see the [atomic reference counted +data][arcbox] API. + +## Automatic pointer clean up + +If you want to add g_autoptr() support to your plain old data type through +reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and +g_rc_box_release(): + +|[<!-- language="C" --> +G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_rc_box_release) +]| + +If you need to clear the contents of the data, you will need to use an +ancillary function that calls g_rc_box_release_full(): + +|[<!-- language="C" --> +static void +my_data_struct_release (MyDataStruct *data) +{ + // my_data_struct_clear() is defined elsewhere + g_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear); +} + +G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release) +]|</doc> + </docsection> + <function name="realloc" c:identifier="g_realloc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the new address of the allocated memory</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="mem" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the memory to reallocate</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_bytes" transfer-ownership="none"> + <doc xml:space="preserve">new size of the memory in bytes</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="realloc_n" c:identifier="g_realloc_n" version="2.24"> + <doc xml:space="preserve">This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes, +but care is taken to detect possible overflow during multiplication.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the new address of the allocated memory</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="mem" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the memory to reallocate</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_blocks" transfer-ownership="none"> + <doc xml:space="preserve">the number of blocks to allocate</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="n_block_bytes" transfer-ownership="none"> + <doc xml:space="preserve">the size of each block in bytes</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="ref_count_compare" c:identifier="g_ref_count_compare" version="2.58"> + <doc xml:space="preserve">Compares the current value of @rc with @val.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the reference count is the same + as the given value</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="rc" transfer-ownership="none"> + <doc xml:space="preserve">the address of a reference count variable</doc> + <type name="gint" c:type="grefcount*"/> + </parameter> + <parameter name="val" transfer-ownership="none"> + <doc xml:space="preserve">the value to compare</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="ref_count_dec" c:identifier="g_ref_count_dec" version="2.58"> + <doc xml:space="preserve">Decreases the reference count.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the reference count reached 0, and %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="rc" transfer-ownership="none"> + <doc xml:space="preserve">the address of a reference count variable</doc> + <type name="gint" c:type="grefcount*"/> + </parameter> + </parameters> + </function> + <function name="ref_count_inc" c:identifier="g_ref_count_inc" version="2.58"> + <doc xml:space="preserve">Increases the reference count.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="rc" transfer-ownership="none"> + <doc xml:space="preserve">the address of a reference count variable</doc> + <type name="gint" c:type="grefcount*"/> + </parameter> + </parameters> + </function> + <function name="ref_count_init" c:identifier="g_ref_count_init" version="2.58"> + <doc xml:space="preserve">Initializes a reference count variable.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="rc" transfer-ownership="none"> + <doc xml:space="preserve">the address of a reference count variable</doc> + <type name="gint" c:type="grefcount*"/> + </parameter> + </parameters> + </function> + <function name="ref_string_acquire" c:identifier="g_ref_string_acquire" version="2.58"> + <doc xml:space="preserve">Acquires a reference on a string.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the given string, with its reference count increased</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a reference counted string</doc> + <type name="utf8" c:type="char*"/> + </parameter> + </parameters> + </function> + <function name="ref_string_length" c:identifier="g_ref_string_length" version="2.58"> + <doc xml:space="preserve">Retrieves the length of @str.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the length of the given string, in bytes</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a reference counted string</doc> + <type name="utf8" c:type="char*"/> + </parameter> + </parameters> + </function> + <function name="ref_string_new" c:identifier="g_ref_string_new" version="2.58"> + <doc xml:space="preserve">Creates a new reference counted string and copies the contents of @str +into it.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the newly created reference counted string</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a NUL-terminated string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="ref_string_new_intern" c:identifier="g_ref_string_new_intern" version="2.58"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the newly created reference + counted string, or a new reference to an existing string</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a NUL-terminated string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="ref_string_new_len" c:identifier="g_ref_string_new_len" version="2.58"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the newly created reference counted string</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">length of @str to use, or -1 if @str is nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function name="ref_string_release" c:identifier="g_ref_string_release" version="2.58"> + <doc xml:space="preserve">Releases a reference on a string; if it was the last reference, the +resources allocated by the string are freed as well.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a reference counted string</doc> + <type name="utf8" c:type="char*"/> + </parameter> + </parameters> + </function> + <docsection name="refcount"> + <doc xml:space="preserve">Reference counting is a garbage collection mechanism that is based on +assigning a counter to a data type, or any memory area; the counter is +increased whenever a new reference to that data type is acquired, and +decreased whenever the reference is released. Once the last reference +is released, the resources associated to that data type are freed. + +GLib uses reference counting in many of its data types, and provides +the #grefcount and #gatomicrefcount types to implement safe and atomic +reference counting semantics in new data types. + +It is important to note that #grefcount and #gatomicrefcount should be +considered completely opaque types; you should always use the provided +API to increase and decrease the counters, and you should never check +their content directly, or compare their content with other values.</doc> + </docsection> + <docsection name="refstring"> + <doc xml:space="preserve">Reference counted strings are normal C strings that have been augmented +with a reference counter to manage their resources. You allocate a new +reference counted string and acquire and release references as needed, +instead of copying the string among callers; when the last reference on +the string is released, the resources allocated for it are freed. + +Typically, reference counted strings can be used when parsing data from +files and storing them into data structures that are passed to various +callers: + +|[<!-- language="C" --> +PersonDetails * +person_details_from_data (const char *data) +{ + // Use g_autoptr() to simplify error cases + g_autoptr(GRefString) full_name = NULL; + g_autoptr(GRefString) address = NULL; + g_autoptr(GRefString) city = NULL; + g_autoptr(GRefString) state = NULL; + g_autoptr(GRefString) zip_code = NULL; + + // parse_person_details() is defined elsewhere; returns refcounted strings + if (!parse_person_details (data, &full_name, &address, &city, &state, &zip_code)) + return NULL; + + if (!validate_zip_code (zip_code)) + return NULL; + + // add_address_to_cache() and add_full_name_to_cache() are defined + // elsewhere; they add strings to various caches, using refcounted + // strings to avoid copying data over and over again + add_address_to_cache (address, city, state, zip_code); + add_full_name_to_cache (full_name); + + // person_details_new() is defined elsewhere; it takes a reference + // on each string + PersonDetails *res = person_details_new (full_name, + address, + city, + state, + zip_code); + + return res; +} +]| + +In the example above, we have multiple functions taking the same strings +for different uses; with typical C strings, we'd have to copy the strings +every time the life time rules of the data differ from the life time of +the string parsed from the original buffer. With reference counted strings, +each caller can take a reference on the data, and keep it as long as it +needs to own the string. + +Reference counted strings can also be "interned" inside a global table +owned by GLib; while an interned string has at least a reference, creating +a new interned reference counted string with the same contents will return +a reference to the existing string instead of creating a new reference +counted string instance. Once the string loses its last reference, it will +be automatically removed from the global interned strings table.</doc> + </docsection> + <function name="regex_check_replacement" c:identifier="g_regex_check_replacement" moved-to="Regex.check_replacement" version="2.14" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether @replacement is a valid replacement string</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="replacement" transfer-ownership="none"> + <doc xml:space="preserve">the replacement string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="has_references" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store information about + references in @replacement or %NULL</doc> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + </parameters> + </function> + <function name="regex_error_quark" c:identifier="g_regex_error_quark" moved-to="Regex.error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="regex_escape_nul" c:identifier="g_regex_escape_nul" moved-to="Regex.escape_nul" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated escaped string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to escape</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @string</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="regex_escape_string" c:identifier="g_regex_escape_string" moved-to="Regex.escape_string" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated escaped string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to escape</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="utf8" c:type="gchar"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @string, in bytes, or -1 if @string is nul-terminated</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="regex_match_simple" c:identifier="g_regex_match_simple" moved-to="Regex.match_simple" version="2.14"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the string matched, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="pattern" transfer-ownership="none"> + <doc xml:space="preserve">the regular expression</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to scan for matches</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="compile_options" transfer-ownership="none"> + <doc xml:space="preserve">compile options for the regular expression, or 0</doc> + <type name="RegexCompileFlags" c:type="GRegexCompileFlags"/> + </parameter> + <parameter name="match_options" transfer-ownership="none"> + <doc xml:space="preserve">match options, or 0</doc> + <type name="RegexMatchFlags" c:type="GRegexMatchFlags"/> + </parameter> + </parameters> + </function> + <function name="regex_split_simple" c:identifier="g_regex_split_simple" moved-to="Regex.split_simple" version="2.14"> + <doc xml:space="preserve">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".</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated array of strings. Free +it using g_strfreev()</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="pattern" transfer-ownership="none"> + <doc xml:space="preserve">the regular expression</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to scan for matches</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="compile_options" transfer-ownership="none"> + <doc xml:space="preserve">compile options for the regular expression, or 0</doc> + <type name="RegexCompileFlags" c:type="GRegexCompileFlags"/> + </parameter> + <parameter name="match_options" transfer-ownership="none"> + <doc xml:space="preserve">match options, or 0</doc> + <type name="RegexMatchFlags" c:type="GRegexMatchFlags"/> + </parameter> + </parameters> + </function> + <function name="reload_user_special_dirs_cache" c:identifier="g_reload_user_special_dirs_cache" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </function> + <function-macro name="renew" c:identifier="g_renew" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="struct_type"> + <doc xml:space="preserve">the type of the elements to allocate</doc> + </parameter> + <parameter name="mem"> + <doc xml:space="preserve">the currently allocated memory</doc> + </parameter> + <parameter name="n_structs"> + <doc xml:space="preserve">the number of elements to allocate</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="return_if_fail" c:identifier="g_return_if_fail" introspectable="0"> + <parameters> + <parameter name="expr"> + </parameter> + </parameters> + </function-macro> + <function name="return_if_fail_warning" c:identifier="g_return_if_fail_warning" introspectable="0"> + <doc xml:space="preserve">Internal function used to print messages from the public g_return_if_fail() +and g_return_val_if_fail() macros.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="log_domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">log domain</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="pretty_function" transfer-ownership="none"> + <doc xml:space="preserve">function containing the assertion</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="expression" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">expression which failed</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function-macro name="return_val_if_fail" c:identifier="g_return_val_if_fail" introspectable="0"> + <parameters> + <parameter name="expr"> + </parameter> + <parameter name="val"> + </parameter> + </parameters> + </function-macro> + <function-macro name="return_val_if_reached" c:identifier="g_return_val_if_reached" introspectable="0"> + <parameters> + <parameter name="val"> + </parameter> + </parameters> + </function-macro> + <function name="rmdir" c:identifier="g_rmdir" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">0 if the directory was successfully removed, -1 if an error + occurred</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">a pathname in the GLib file name encoding + (UTF-8 on Windows)</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <docsection name="scanner"> + <doc xml:space="preserve">The #GScanner and its associated functions provide a +general purpose lexical scanner.</doc> + </docsection> + <function-macro name="scanner_add_symbol" c:identifier="g_scanner_add_symbol" introspectable="0" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">Adds a symbol to the default scope.</doc> + <doc-deprecated xml:space="preserve">Use g_scanner_scope_add_symbol() instead.</doc-deprecated> + <parameters> + <parameter name="scanner"> + <doc xml:space="preserve">a #GScanner</doc> + </parameter> + <parameter name="symbol"> + <doc xml:space="preserve">the symbol to add</doc> + </parameter> + <parameter name="value"> + <doc xml:space="preserve">the value of the symbol</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="scanner_foreach_symbol" c:identifier="g_scanner_foreach_symbol" introspectable="0" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">Calls a function for each symbol in the default scope.</doc> + <doc-deprecated xml:space="preserve">Use g_scanner_scope_foreach_symbol() instead.</doc-deprecated> + <parameters> + <parameter name="scanner"> + <doc xml:space="preserve">a #GScanner</doc> + </parameter> + <parameter name="func"> + <doc xml:space="preserve">the function to call with each symbol</doc> + </parameter> + <parameter name="data"> + <doc xml:space="preserve">data to pass to the function</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="scanner_freeze_symbol_table" c:identifier="g_scanner_freeze_symbol_table" introspectable="0" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">There is no reason to use this macro, since it does nothing.</doc> + <doc-deprecated xml:space="preserve">This macro does nothing.</doc-deprecated> + <parameters> + <parameter name="scanner"> + <doc xml:space="preserve">a #GScanner</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="scanner_remove_symbol" c:identifier="g_scanner_remove_symbol" introspectable="0" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">Removes a symbol from the default scope.</doc> + <doc-deprecated xml:space="preserve">Use g_scanner_scope_remove_symbol() instead.</doc-deprecated> + <parameters> + <parameter name="scanner"> + <doc xml:space="preserve">a #GScanner</doc> + </parameter> + <parameter name="symbol"> + <doc xml:space="preserve">the symbol to remove</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="scanner_thaw_symbol_table" c:identifier="g_scanner_thaw_symbol_table" introspectable="0" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">There is no reason to use this macro, since it does nothing.</doc> + <doc-deprecated xml:space="preserve">This macro does nothing.</doc-deprecated> + <parameters> + <parameter name="scanner"> + <doc xml:space="preserve">a #GScanner</doc> + </parameter> + </parameters> + </function-macro> + <docsection name="sequence"> + <doc xml:space="preserve">The #GSequence data structure has the API of a list, but is +implemented internally with a balanced binary tree. This means that +most of the operations (access, search, insertion, deletion, ...) on +#GSequence are O(log(n)) in average and O(n) in worst case for time +complexity. But, note that maintaining a balanced sorted list of n +elements is done in time O(n log(n)). +The data contained in each element can be either integer values, by using +of the [Type Conversion Macros][glib-Type-Conversion-Macros], or simply +pointers to any type of data. + +A #GSequence is accessed through "iterators", represented by a +#GSequenceIter. An iterator represents a position between two +elements of the sequence. For example, the "begin" iterator +represents the gap immediately before the first element of the +sequence, and the "end" iterator represents the gap immediately +after the last element. In an empty sequence, the begin and end +iterators are the same. + +Some methods on #GSequence operate on ranges of items. For example +g_sequence_foreach_range() will call a user-specified function on +each element with the given range. The range is delimited by the +gaps represented by the passed-in iterators, so if you pass in the +begin and end iterators, the range in question is the entire +sequence. + +The function g_sequence_get() is used with an iterator to access the +element immediately following the gap that the iterator represents. +The iterator is said to "point" to that element. + +Iterators are stable across most operations on a #GSequence. For +example an iterator pointing to some element of a sequence will +continue to point to that element even after the sequence is sorted. +Even moving an element to another sequence using for example +g_sequence_move_range() will not invalidate the iterators pointing +to it. The only operation that will invalidate an iterator is when +the element it points to is removed from any sequence. + +To sort the data, either use g_sequence_insert_sorted() or +g_sequence_insert_sorted_iter() to add data to the #GSequence or, if +you want to add a large amount of data, it is more efficient to call +g_sequence_sort() or g_sequence_sort_iter() after doing unsorted +insertions.</doc> + </docsection> + <function name="sequence_get" c:identifier="g_sequence_get" moved-to="Sequence.get" version="2.14"> + <doc xml:space="preserve">Returns the data that @iter points to.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the data that @iter points to</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + </parameters> + </function> + <function name="sequence_insert_before" c:identifier="g_sequence_insert_before" moved-to="Sequence.insert_before" version="2.14"> + <doc xml:space="preserve">Inserts a new item just before the item pointed to by @iter.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an iterator pointing to the new item</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data for the new item</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="sequence_move" c:identifier="g_sequence_move" moved-to="Sequence.move" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="src" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter pointing to the item to move</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="dest" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter pointing to the position to which + the item is moved</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + </parameters> + </function> + <function name="sequence_move_range" c:identifier="g_sequence_move_range" moved-to="Sequence.move_range" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="dest" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="begin" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="end" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + </parameters> + </function> + <function name="sequence_range_get_midpoint" c:identifier="g_sequence_range_get_midpoint" moved-to="Sequence.range_get_midpoint" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter pointing somewhere in the + (@begin, @end) range</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </return-value> + <parameters> + <parameter name="begin" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="end" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + </parameters> + </function> + <function name="sequence_remove" c:identifier="g_sequence_remove" moved-to="Sequence.remove" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + </parameters> + </function> + <function name="sequence_remove_range" c:identifier="g_sequence_remove_range" moved-to="Sequence.remove_range" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="begin" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="end" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + </parameters> + </function> + <function name="sequence_set" c:identifier="g_sequence_set" moved-to="Sequence.set" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">new data for the item</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="sequence_swap" c:identifier="g_sequence_swap" moved-to="Sequence.swap" version="2.14"> + <doc xml:space="preserve">Swaps the items pointed to by @a and @b. It is allowed for @a and @b +to point into difference sequences.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="a" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + <parameter name="b" transfer-ownership="none"> + <doc xml:space="preserve">a #GSequenceIter</doc> + <type name="SequenceIter" c:type="GSequenceIter*"/> + </parameter> + </parameters> + </function> + <function name="set_application_name" c:identifier="g_set_application_name" version="2.2"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="application_name" transfer-ownership="none"> + <doc xml:space="preserve">localized name of the application</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="set_error" c:identifier="g_set_error" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="err" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a return location for a #GError</doc> + <type name="Error" c:type="GError**"/> + </parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">error domain</doc> + <type name="Quark" c:type="GQuark"/> + </parameter> + <parameter name="code" transfer-ownership="none"> + <doc xml:space="preserve">error code</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">printf()-style format</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">args for @format</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="set_error_literal" c:identifier="g_set_error_literal" version="2.18"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="err" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a return location for a #GError</doc> + <type name="Error" c:type="GError**"/> + </parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">error domain</doc> + <type name="Quark" c:type="GQuark"/> + </parameter> + <parameter name="code" transfer-ownership="none"> + <doc xml:space="preserve">error code</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">error message</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="set_prgname" c:identifier="g_set_prgname"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="prgname" transfer-ownership="none"> + <doc xml:space="preserve">the name of the program.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="set_print_handler" c:identifier="g_set_print_handler" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the old print handler</doc> + <type name="PrintFunc" c:type="GPrintFunc"/> + </return-value> + <parameters> + <parameter name="func" transfer-ownership="none"> + <doc xml:space="preserve">the new print handler</doc> + <type name="PrintFunc" c:type="GPrintFunc"/> + </parameter> + </parameters> + </function> + <function name="set_printerr_handler" c:identifier="g_set_printerr_handler" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the old error message handler</doc> + <type name="PrintFunc" c:type="GPrintFunc"/> + </return-value> + <parameters> + <parameter name="func" transfer-ownership="none"> + <doc xml:space="preserve">the new error message handler</doc> + <type name="PrintFunc" c:type="GPrintFunc"/> + </parameter> + </parameters> + </function> + <function name="setenv" c:identifier="g_setenv" version="2.4"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%FALSE if the environment variable couldn't be set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="variable" transfer-ownership="none"> + <doc xml:space="preserve">the environment variable to set, must not + contain '='.</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value for to set the variable to.</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="overwrite" transfer-ownership="none"> + <doc xml:space="preserve">whether to change the variable if it already exists.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <docsection name="shell"> + <doc xml:space="preserve">GLib provides the functions g_shell_quote() and g_shell_unquote() +to handle shell-like quoting in strings. The function g_shell_parse_argv() +parses a string similar to the way a POSIX shell (/bin/sh) would. + +Note that string handling in shells has many obscure and historical +corner-cases which these functions do not necessarily reproduce. They +are good enough in practice, though.</doc> + </docsection> + <function name="shell_error_quark" c:identifier="g_shell_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="shell_parse_argv" c:identifier="g_shell_parse_argv" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if error set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="command_line" transfer-ownership="none"> + <doc xml:space="preserve">command line to parse</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="argcp" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for number of args</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="argvp" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve"> + return location for array of args</doc> + <array length="1" zero-terminated="1" c:type="gchar***"> + <type name="filename"/> + </array> + </parameter> + </parameters> + </function> + <function name="shell_quote" c:identifier="g_shell_quote"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">quoted string</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="unquoted_string" transfer-ownership="none"> + <doc xml:space="preserve">a literal string</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="shell_unquote" c:identifier="g_shell_unquote" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an unquoted string</doc> + <type name="filename" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="quoted_string" transfer-ownership="none"> + <doc xml:space="preserve">shell-quoted string</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function-macro name="size_checked_add" c:identifier="g_size_checked_add" version="2.48" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="dest"> + <doc xml:space="preserve">a pointer to the #gsize destination</doc> + </parameter> + <parameter name="a"> + <doc xml:space="preserve">the #gsize left operand</doc> + </parameter> + <parameter name="b"> + <doc xml:space="preserve">the #gsize right operand</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="size_checked_mul" c:identifier="g_size_checked_mul" version="2.48" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="dest"> + <doc xml:space="preserve">a pointer to the #gsize destination</doc> + </parameter> + <parameter name="a"> + <doc xml:space="preserve">the #gsize left operand</doc> + </parameter> + <parameter name="b"> + <doc xml:space="preserve">the #gsize right operand</doc> + </parameter> + </parameters> + </function-macro> + <function name="slice_alloc" c:identifier="g_slice_alloc" version="2.10"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a pointer to the allocated memory block, which will be %NULL if and + only if @mem_size is 0</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="block_size" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to allocate</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="slice_alloc0" c:identifier="g_slice_alloc0" version="2.10"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a pointer to the allocated block, which will be %NULL if and only + if @mem_size is 0</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="block_size" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to allocate</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="slice_copy" c:identifier="g_slice_copy" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a pointer to the allocated memory block, which will be %NULL if and + only if @mem_size is 0</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="block_size" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to allocate</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="mem_block" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the memory to copy</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function-macro name="slice_dup" c:identifier="g_slice_dup" version="2.14" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">the type to duplicate, typically a structure name</doc> + </parameter> + <parameter name="mem"> + <doc xml:space="preserve">the memory to copy into the allocated block</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="slice_free" c:identifier="g_slice_free" version="2.10" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">the type of the block to free, typically a structure name</doc> + </parameter> + <parameter name="mem"> + <doc xml:space="preserve">a pointer to the block to free</doc> + </parameter> + </parameters> + </function-macro> + <function name="slice_free1" c:identifier="g_slice_free1" version="2.10"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="block_size" transfer-ownership="none"> + <doc xml:space="preserve">the size of the block</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="mem_block" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to the block to free</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function-macro name="slice_free_chain" c:identifier="g_slice_free_chain" version="2.10" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">the type of the @mem_chain blocks</doc> + </parameter> + <parameter name="mem_chain"> + <doc xml:space="preserve">a pointer to the first block of the chain</doc> + </parameter> + <parameter name="next"> + <doc xml:space="preserve">the field name of the next pointer in @type</doc> + </parameter> + </parameters> + </function-macro> + <function name="slice_free_chain_with_offset" c:identifier="g_slice_free_chain_with_offset" version="2.10"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="block_size" transfer-ownership="none"> + <doc xml:space="preserve">the size of the blocks</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="mem_chain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to the first block of the chain</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="next_offset" transfer-ownership="none"> + <doc xml:space="preserve">the offset of the @next field in the blocks</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="slice_get_config" c:identifier="g_slice_get_config"> + <return-value transfer-ownership="none"> + <type name="gint64" c:type="gint64"/> + </return-value> + <parameters> + <parameter name="ckey" transfer-ownership="none"> + <type name="SliceConfig" c:type="GSliceConfig"/> + </parameter> + </parameters> + </function> + <function name="slice_get_config_state" c:identifier="g_slice_get_config_state"> + <return-value transfer-ownership="none"> + <type name="gint64" c:type="gint64*"/> + </return-value> + <parameters> + <parameter name="ckey" transfer-ownership="none"> + <type name="SliceConfig" c:type="GSliceConfig"/> + </parameter> + <parameter name="address" transfer-ownership="none"> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="n_values" transfer-ownership="none"> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </function> + <function-macro name="slice_new" c:identifier="g_slice_new" version="2.10" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">the type to allocate, typically a structure name</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="slice_new0" c:identifier="g_slice_new0" version="2.10" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">the type to allocate, typically a structure name</doc> + </parameter> + </parameters> + </function-macro> + <function name="slice_set_config" c:identifier="g_slice_set_config"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="ckey" transfer-ownership="none"> + <type name="SliceConfig" c:type="GSliceConfig"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="gint64" c:type="gint64"/> + </parameter> + </parameters> + </function> + <function-macro name="slist_next" c:identifier="g_slist_next" introspectable="0"> + <doc xml:space="preserve">A convenience macro to get the next element in a #GSList. +Note that it is considered perfectly acceptable to access +@slist->next directly.</doc> + <parameters> + <parameter name="slist"> + <doc xml:space="preserve">an element in a #GSList.</doc> + </parameter> + </parameters> + </function-macro> + <function name="snprintf" c:identifier="g_snprintf" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes which would be produced if the buffer + was large enough.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the buffer to hold the output.</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">the maximum number of bytes to produce (including the + terminating nul character).</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a standard printf() format string, but notice + [string precision pitfalls][string-precision]</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the arguments to insert in the output.</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="source_remove" c:identifier="g_source_remove" moved-to="Source.remove"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">For historical reasons, this function always returns %TRUE</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="tag" transfer-ownership="none"> + <doc xml:space="preserve">the ID of the source to remove.</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="source_remove_by_funcs_user_data" c:identifier="g_source_remove_by_funcs_user_data" moved-to="Source.remove_by_funcs_user_data"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a source was found and removed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="funcs" transfer-ownership="none"> + <doc xml:space="preserve">The @source_funcs passed to g_source_new()</doc> + <type name="SourceFuncs" c:type="GSourceFuncs*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the user data for the callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="source_remove_by_user_data" c:identifier="g_source_remove_by_user_data" moved-to="Source.remove_by_user_data"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a source was found and removed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the user_data for the callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="source_set_name_by_id" c:identifier="g_source_set_name_by_id" moved-to="Source.set_name_by_id" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="tag" transfer-ownership="none"> + <doc xml:space="preserve">a #GSource ID</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">debug name for the source</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="spaced_primes_closest" c:identifier="g_spaced_primes_closest"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the smallest prime number from a built-in array of primes + which is larger than @num</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="num" transfer-ownership="none"> + <doc xml:space="preserve">a #guint</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <docsection name="spawn"> + <doc xml:space="preserve">GLib supports spawning of processes with an API that is more +convenient than the bare UNIX fork() and exec(). + +The g_spawn family of functions has synchronous (g_spawn_sync()) +and asynchronous variants (g_spawn_async(), g_spawn_async_with_pipes()), +as well as convenience variants that take a complete shell-like +commandline (g_spawn_command_line_sync(), g_spawn_command_line_async()). + +See #GSubprocess in GIO for a higher-level API that provides +stream interfaces for communication with child processes. + +An example of using g_spawn_async_with_pipes(): +|[<!-- language="C" --> +const gchar * const argv[] = { "my-favourite-program", "--args", NULL }; +gint child_stdout, child_stderr; +GPid child_pid; +g_autoptr(GError) error = NULL; + +// Spawn child process. +g_spawn_async_with_pipes (NULL, argv, NULL, G_SPAWN_DO_NOT_REAP_CHILD, NULL, + NULL, &child_pid, NULL, &child_stdout, + &child_stderr, &error); +if (error != NULL) + { + g_error ("Spawning child failed: %s", error->message); + return; + } + +// Add a child watch function which will be called when the child process +// exits. +g_child_watch_add (child_pid, child_watch_cb, NULL); + +// You could watch for output on @child_stdout and @child_stderr using +// #GUnixInputStream or #GIOChannel here. + +static void +child_watch_cb (GPid pid, + gint status, + gpointer user_data) +{ + g_message ("Child %" G_PID_FORMAT " exited %s", pid, + g_spawn_check_exit_status (status, NULL) ? "normally" : "abnormally"); + + // Free any resources associated with the child here, such as I/O channels + // on its stdout and stderr FDs. If you have no code to put in the + // child_watch_cb() callback, you can remove it and the g_child_watch_add() + // call, but you must also remove the G_SPAWN_DO_NOT_REAP_CHILD flag, + // otherwise the child process will stay around as a zombie until this + // process exits. + + g_spawn_close_pid (pid); +} +]|</doc> + </docsection> + <function name="spawn_async" c:identifier="g_spawn_async" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if error is set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="working_directory" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">child's current working + directory, or %NULL to inherit parent's</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="argv" transfer-ownership="none"> + <doc xml:space="preserve"> + child's argument vector</doc> + <array c:type="gchar**"> + <type name="filename"/> + </array> + </parameter> + <parameter name="envp" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve"> + child's environment, or %NULL to inherit parent's</doc> + <array c:type="gchar**"> + <type name="filename"/> + </array> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags from #GSpawnFlags</doc> + <type name="SpawnFlags" c:type="GSpawnFlags"/> + </parameter> + <parameter name="child_setup" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">function to run in the child just before exec()</doc> + <type name="SpawnChildSetupFunc" c:type="GSpawnChildSetupFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data for @child_setup</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="child_pid" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for child process reference, or %NULL</doc> + <type name="Pid" c:type="GPid*"/> + </parameter> + </parameters> + </function> + <function name="spawn_async_with_fds" c:identifier="g_spawn_async_with_fds" version="2.58" throws="1"> + <doc xml:space="preserve">Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero, +so no FD assignments are used.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if an error was set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="working_directory" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="argv" transfer-ownership="none"> + <doc xml:space="preserve">child's argument vector, in the GLib file name encoding</doc> + <array c:type="gchar**"> + <type name="utf8" c:type="gchar*"/> + </array> + </parameter> + <parameter name="envp" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">child's environment, or %NULL to inherit parent's, in the GLib file name encoding</doc> + <array c:type="gchar**"> + <type name="utf8" c:type="gchar*"/> + </array> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags from #GSpawnFlags</doc> + <type name="SpawnFlags" c:type="GSpawnFlags"/> + </parameter> + <parameter name="child_setup" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">function to run in the child just before exec()</doc> + <type name="SpawnChildSetupFunc" c:type="GSpawnChildSetupFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data for @child_setup</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="child_pid" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for child process ID, or %NULL</doc> + <type name="Pid" c:type="GPid*"/> + </parameter> + <parameter name="stdin_fd" transfer-ownership="none"> + <doc xml:space="preserve">file descriptor to use for child's stdin, or `-1`</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="stdout_fd" transfer-ownership="none"> + <doc xml:space="preserve">file descriptor to use for child's stdout, or `-1`</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="stderr_fd" transfer-ownership="none"> + <doc xml:space="preserve">file descriptor to use for child's stderr, or `-1`</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="spawn_async_with_pipes" c:identifier="g_spawn_async_with_pipes" throws="1"> + <doc xml:space="preserve">Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero, +so no FD assignments are used.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if an error was set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="working_directory" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">child's current working + directory, or %NULL to inherit parent's, in the GLib file name encoding</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="argv" transfer-ownership="none"> + <doc xml:space="preserve">child's argument + vector, in the GLib file name encoding</doc> + <array c:type="gchar**"> + <type name="filename"/> + </array> + </parameter> + <parameter name="envp" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve"> + child's environment, or %NULL to inherit parent's, in the GLib file + name encoding</doc> + <array c:type="gchar**"> + <type name="filename"/> + </array> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags from #GSpawnFlags</doc> + <type name="SpawnFlags" c:type="GSpawnFlags"/> + </parameter> + <parameter name="child_setup" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">function to run in the child just before exec()</doc> + <type name="SpawnChildSetupFunc" c:type="GSpawnChildSetupFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data for @child_setup</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="child_pid" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for child process ID, or %NULL</doc> + <type name="Pid" c:type="GPid*"/> + </parameter> + <parameter name="standard_input" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for file descriptor to write to child's stdin, or %NULL</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="standard_output" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for file descriptor to read child's stdout, or %NULL</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="standard_error" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for file descriptor to read child's stderr, or %NULL</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </function> + <function name="spawn_check_exit_status" c:identifier="g_spawn_check_exit_status" version="2.34" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if child exited successfully, %FALSE otherwise (and + @error will be set)</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="exit_status" transfer-ownership="none"> + <doc xml:space="preserve">An exit code as returned from g_spawn_sync()</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="spawn_close_pid" c:identifier="g_spawn_close_pid"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="pid" transfer-ownership="none"> + <doc xml:space="preserve">The process reference to close</doc> + <type name="Pid" c:type="GPid"/> + </parameter> + </parameters> + </function> + <function name="spawn_command_line_async" c:identifier="g_spawn_command_line_async" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if error is set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="command_line" transfer-ownership="none"> + <doc xml:space="preserve">a command line</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="spawn_command_line_sync" c:identifier="g_spawn_command_line_sync" throws="1"> + <doc xml:space="preserve">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'".</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if an error was set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="command_line" transfer-ownership="none"> + <doc xml:space="preserve">a command line</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="standard_output" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for child output</doc> + <array c:type="gchar**"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="standard_error" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for child errors</doc> + <array c:type="gchar**"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="exit_status" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for child exit status, as returned by waitpid()</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </function> + <function name="spawn_error_quark" c:identifier="g_spawn_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="spawn_exit_error_quark" c:identifier="g_spawn_exit_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="spawn_sync" c:identifier="g_spawn_sync" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if an error was set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="working_directory" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">child's current working + directory, or %NULL to inherit parent's</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="argv" transfer-ownership="none"> + <doc xml:space="preserve"> + child's argument vector</doc> + <array c:type="gchar**"> + <type name="filename"/> + </array> + </parameter> + <parameter name="envp" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve"> + child's environment, or %NULL to inherit parent's</doc> + <array c:type="gchar**"> + <type name="filename"/> + </array> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags from #GSpawnFlags</doc> + <type name="SpawnFlags" c:type="GSpawnFlags"/> + </parameter> + <parameter name="child_setup" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">function to run in the child just before exec()</doc> + <type name="SpawnChildSetupFunc" c:type="GSpawnChildSetupFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data for @child_setup</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="standard_output" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for child output, or %NULL</doc> + <array c:type="gchar**"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="standard_error" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for child error messages, or %NULL</doc> + <array c:type="gchar**"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="exit_status" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for child exit status, as returned by waitpid(), or %NULL</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </function> + <function name="sprintf" c:identifier="g_sprintf" version="2.2" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes printed.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">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</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a standard printf() format string, but notice + [string precision pitfalls][string-precision]</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the arguments to insert in the output.</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function-macro name="steal_pointer" c:identifier="g_steal_pointer" version="2.44" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="pp"> + <doc xml:space="preserve">a pointer to a pointer</doc> + </parameter> + </parameters> + </function-macro> + <function name="stpcpy" c:identifier="g_stpcpy"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to trailing nul byte.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="dest" transfer-ownership="none"> + <doc xml:space="preserve">destination buffer.</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="src" transfer-ownership="none"> + <doc xml:space="preserve">source string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="str_equal" c:identifier="g_str_equal"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the two keys match</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="v1" transfer-ownership="none"> + <doc xml:space="preserve">a key</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="v2" transfer-ownership="none"> + <doc xml:space="preserve">a key to compare with @v1</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="str_has_prefix" c:identifier="g_str_has_prefix" version="2.2"> + <doc xml:space="preserve">Looks whether the string @str begins with @prefix.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @str begins with @prefix, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a nul-terminated string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="prefix" transfer-ownership="none"> + <doc xml:space="preserve">the nul-terminated prefix to look for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="str_has_suffix" c:identifier="g_str_has_suffix" version="2.2"> + <doc xml:space="preserve">Looks whether the string @str ends with @suffix.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @str end with @suffix, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a nul-terminated string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="suffix" transfer-ownership="none"> + <doc xml:space="preserve">the nul-terminated suffix to look for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="str_hash" c:identifier="g_str_hash"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a hash value corresponding to the key</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="v" transfer-ownership="none"> + <doc xml:space="preserve">a string key</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="str_is_ascii" c:identifier="g_str_is_ascii" version="2.40"> + <doc xml:space="preserve">Determines if a string is pure ASCII. A string is pure ASCII if it +contains no bytes with the high bit set.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @str is ASCII</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="str_match_string" c:identifier="g_str_match_string" version="2.40"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @potential_hit is a hit</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="search_term" transfer-ownership="none"> + <doc xml:space="preserve">the search term from the user</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="potential_hit" transfer-ownership="none"> + <doc xml:space="preserve">the text that may be a hit</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="accept_alternates" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to accept ASCII alternates</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="str_to_ascii" c:identifier="g_str_to_ascii" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a string in plain ASCII</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a string, in UTF-8</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="from_locale" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the source locale, if known</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="str_tokenize_and_fold" c:identifier="g_str_tokenize_and_fold" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the folded tokens</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="translit_locale" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the language code (like 'de' or + 'en_GB') from which @string originates</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="ascii_alternates" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">a + return location for ASCII alternates</doc> + <array c:type="gchar***"> + <type name="utf8" c:type="gchar**"/> + </array> + </parameter> + </parameters> + </function> + <function name="strcanon" c:identifier="g_strcanon"> + <doc xml:space="preserve">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); +]|</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">@string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a nul-terminated array of bytes</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="valid_chars" transfer-ownership="none"> + <doc xml:space="preserve">bytes permitted in @string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="substitutor" transfer-ownership="none"> + <doc xml:space="preserve">replacement character for disallowed bytes</doc> + <type name="gchar" c:type="gchar"/> + </parameter> + </parameters> + </function> + <function name="strcasecmp" c:identifier="g_strcasecmp" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">A case-insensitive string comparison, corresponding to the standard +strcasecmp() function on platforms which support it.</doc> + <doc-deprecated xml:space="preserve">See g_strncasecmp() for a discussion of why this + function is deprecated and how to replace it.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">0 if the strings match, a negative value if @s1 < @s2, + or a positive value if @s1 > @s2.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="s1" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="s2" transfer-ownership="none"> + <doc xml:space="preserve">a string to compare with @s1</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="strchomp" c:identifier="g_strchomp"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">@string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a string to remove the trailing whitespace from</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </function> + <function name="strchug" c:identifier="g_strchug"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">@string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a string to remove the leading whitespace from</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </function> + <function name="strcmp0" c:identifier="g_strcmp0" version="2.16"> + <doc xml:space="preserve">Compares @str1 and @str2 like strcmp(). Handles %NULL +gracefully by sorting it before non-%NULL strings. +Comparing two %NULL pointers returns 0.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an integer less than, equal to, or greater than zero, if @str1 is <, == or > than @str2.</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <parameter name="str1" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a C string or %NULL</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="str2" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">another C string or %NULL</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="strcompress" c:identifier="g_strcompress"> + <doc xml:space="preserve">Replaces all escaped characters with their one byte equivalent. + +This function does the reverse conversion of g_strescape().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated copy of @source with all escaped + character compressed</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a string to compress</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="strconcat" c:identifier="g_strconcat" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated string containing all the string arguments</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="string1" transfer-ownership="none"> + <doc xml:space="preserve">the first string to add, which must not be %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">a %NULL-terminated list of strings to append to the string</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="strdelimit" c:identifier="g_strdelimit"> + <doc xml:space="preserve">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); +]|</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">@string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to convert</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="delimiters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string containing the current delimiters, + or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="new_delimiter" transfer-ownership="none"> + <doc xml:space="preserve">the new delimiter character</doc> + <type name="gchar" c:type="gchar"/> + </parameter> + </parameters> + </function> + <function name="strdown" c:identifier="g_strdown" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">Converts a string to lower case.</doc> + <doc-deprecated xml:space="preserve">This function is totally broken for the reasons discussed +in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown() +instead.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to convert.</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </function> + <function name="strdup" c:identifier="g_strdup"> + <doc xml:space="preserve">Duplicates a string. If @str is %NULL it returns %NULL. +The returned string should be freed with g_free() +when no longer needed.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated copy of @str</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the string to duplicate</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="strdup_printf" c:identifier="g_strdup_printf" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated string holding the result</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a standard printf() format string, but notice + [string precision pitfalls][string-precision]</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the parameters to insert into the format string</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="strdup_vprintf" c:identifier="g_strdup_vprintf" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated string holding the result</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a standard printf() format string, but notice + [string precision pitfalls][string-precision]</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">the list of parameters to insert into the format string</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </function> + <function name="strdupv" c:identifier="g_strdupv" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value nullable="1"> + <doc xml:space="preserve">a new %NULL-terminated array of strings.</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="str_array" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %NULL-terminated array of strings</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </function> + <function name="strerror" c:identifier="g_strerror"> + <doc xml:space="preserve">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); +]|</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 string describing the error code. If the error code + is unknown, it returns a string like "unknown error (<code>)".</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="errnum" transfer-ownership="none"> + <doc xml:space="preserve">the system error number. See the standard C %errno + documentation</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="strescape" c:identifier="g_strescape"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated copy of @source with certain + characters escaped. See above.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a string to escape</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="exceptions" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string of characters not to escape in @source</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="strfreev" c:identifier="g_strfreev"> + <doc xml:space="preserve">Frees a %NULL-terminated array of strings, as well as each +string it contains. + +If @str_array is %NULL, this function simply returns.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="str_array" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %NULL-terminated array of strings to free</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </function> + <docsection name="string_chunks"> + <doc xml:space="preserve">String chunks are used to store groups of strings. Memory is +allocated in blocks, and as strings are added to the #GStringChunk +they are copied into the next free position in a block. When a block +is full a new block is allocated. + +When storing a large number of strings, string chunks are more +efficient than using g_strdup() since fewer calls to malloc() are +needed, and less memory is wasted in memory allocation overheads. + +By adding strings with g_string_chunk_insert_const() it is also +possible to remove duplicates. + +To create a new #GStringChunk use g_string_chunk_new(). + +To add strings to a #GStringChunk use g_string_chunk_insert(). + +To add strings to a #GStringChunk, but without duplicating strings +which are already in the #GStringChunk, use +g_string_chunk_insert_const(). + +To free the entire #GStringChunk use g_string_chunk_free(). It is +not possible to free individual strings.</doc> + </docsection> + <function name="string_new" c:identifier="g_string_new"> + <doc xml:space="preserve">Creates a new #GString, initialized with the given string.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new #GString</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <parameter name="init" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the initial text to copy into the string, or %NULL to +start with an empty string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="string_new_len" c:identifier="g_string_new_len"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GString</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <parameter name="init" transfer-ownership="none"> + <doc xml:space="preserve">initial contents of the string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">length of @init to use</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function name="string_sized_new" c:identifier="g_string_sized_new"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new #GString</doc> + <type name="String" c:type="GString*"/> + </return-value> + <parameters> + <parameter name="dfl_size" transfer-ownership="none"> + <doc xml:space="preserve">the default size of the space allocated to + hold the string</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <docsection name="string_utils"> + <doc xml:space="preserve">This section describes a number of utility functions for creating, +duplicating, and manipulating strings. + +Note that the functions g_printf(), g_fprintf(), g_sprintf(), +g_vprintf(), g_vfprintf(), g_vsprintf() and g_vasprintf() +are declared in the header `gprintf.h` which is not included in `glib.h` +(otherwise using `glib.h` would drag in `stdio.h`), so you'll have to +explicitly include `<glib/gprintf.h>` in order to use the GLib +printf() functions. + +## String precision pitfalls # {#string-precision} + +While you may use the printf() functions to format UTF-8 strings, +notice that the precision of a \%Ns parameter is interpreted +as the number of bytes, not characters to print. On top of that, +the GNU libc implementation of the printf() functions has the +"feature" that it checks that the string given for the \%Ns +parameter consists of a whole number of characters in the current +encoding. So, unless you are sure you are always going to be in an +UTF-8 locale or your know your text is restricted to ASCII, avoid +using \%Ns. If your intention is to format strings for a +certain number of columns, then \%Ns is not a correct solution +anyway, since it fails to take wide characters (see g_unichar_iswide()) +into account. + +Note also that there are various printf() parameters which are platform +dependent. GLib provides platform independent macros for these parameters +which should be used instead. A common example is %G_GUINT64_FORMAT, which +should be used instead of `%llu` or similar parameters for formatting +64-bit integers. These macros are all named `G_*_FORMAT`; see +[Basic Types][glib-Basic-Types].</doc> + </docsection> + <docsection name="strings"> + <doc xml:space="preserve">A #GString is an object that handles the memory management of a C +string for you. The emphasis of #GString is on text, typically +UTF-8. Crucially, the "str" member of a #GString is guaranteed to +have a trailing nul character, and it is therefore always safe to +call functions such as strchr() or g_strdup() on it. + +However, a #GString can also hold arbitrary binary data, because it +has a "len" member, which includes any possible embedded nul +characters in the data. Conceptually then, #GString is like a +#GByteArray with the addition of many convenience methods for text, +and a guaranteed nul terminator.</doc> + </docsection> + <function name="strip_context" c:identifier="g_strip_context" version="2.4"> + <doc xml:space="preserve">An auxiliary function for gettext() support (see Q_()).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@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.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="msgid" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="msgval" transfer-ownership="none"> + <doc xml:space="preserve">another string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="strjoin" c:identifier="g_strjoin" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated string containing all of the strings joined + together, with @separator between them</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="separator" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string to insert between each of the + strings, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">a %NULL-terminated list of strings to join</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="strjoinv" c:identifier="g_strjoinv"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated string containing all of the strings joined + together, with @separator between them</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="separator" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string to insert between each of the + strings, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="str_array" transfer-ownership="none"> + <doc xml:space="preserve">a %NULL-terminated array of strings to join</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </function> + <function name="strlcat" c:identifier="g_strlcat"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">size of attempted result, which is MIN (dest_size, strlen + (original dest)) + strlen (src), so if retval >= dest_size, + truncation occurred.</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="dest" transfer-ownership="none"> + <doc xml:space="preserve">destination buffer, already containing one nul-terminated string</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="src" transfer-ownership="none"> + <doc xml:space="preserve">source buffer</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="dest_size" transfer-ownership="none"> + <doc xml:space="preserve">length of @dest buffer in bytes (not length of existing string + inside @dest)</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="strlcpy" c:identifier="g_strlcpy"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">length of @src</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="dest" transfer-ownership="none"> + <doc xml:space="preserve">destination buffer</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="src" transfer-ownership="none"> + <doc xml:space="preserve">source buffer</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="dest_size" transfer-ownership="none"> + <doc xml:space="preserve">length of @dest in bytes</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="strncasecmp" c:identifier="g_strncasecmp" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">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.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">0 if the strings match, a negative value if @s1 < @s2, + or a positive value if @s1 > @s2.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="s1" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="s2" transfer-ownership="none"> + <doc xml:space="preserve">a string to compare with @s1</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">the maximum number of characters to compare</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="strndup" c:identifier="g_strndup"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated buffer containing the first @n bytes + of @str, nul-terminated</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">the string to duplicate</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">the maximum number of bytes to copy from @str</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="strnfill" c:identifier="g_strnfill"> + <doc xml:space="preserve">Creates a new string @length bytes long filled with @fill_char. +The returned string should be freed when no longer needed.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated string filled the @fill_char</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of the new string</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="fill_char" transfer-ownership="none"> + <doc xml:space="preserve">the byte to fill the string with</doc> + <type name="gchar" c:type="gchar"/> + </parameter> + </parameters> + </function> + <function name="strreverse" c:identifier="g_strreverse"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the same pointer passed in as @string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to reverse</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </function> + <function name="strrstr" c:identifier="g_strrstr"> + <doc xml:space="preserve">Searches the string @haystack for the last occurrence +of the string @needle.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to the found occurrence, or + %NULL if not found.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="haystack" transfer-ownership="none"> + <doc xml:space="preserve">a nul-terminated string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="needle" transfer-ownership="none"> + <doc xml:space="preserve">the nul-terminated string to search for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="strrstr_len" c:identifier="g_strrstr_len"> + <doc xml:space="preserve">Searches the string @haystack for the last occurrence +of the string @needle, limiting the length of the search +to @haystack_len.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to the found occurrence, or + %NULL if not found.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="haystack" transfer-ownership="none"> + <doc xml:space="preserve">a nul-terminated string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="haystack_len" transfer-ownership="none"> + <doc xml:space="preserve">the maximum length of @haystack in bytes. A length of -1 + can be used to mean "search the entire string", like g_strrstr().</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="needle" transfer-ownership="none"> + <doc xml:space="preserve">the nul-terminated string to search for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="strsignal" c:identifier="g_strsignal"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 string describing the signal. If the signal is unknown, + it returns "unknown signal (<signum>)".</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="signum" transfer-ownership="none"> + <doc xml:space="preserve">the signal number. See the `signal` documentation</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="strsplit" c:identifier="g_strsplit" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value> + <doc xml:space="preserve">a newly-allocated %NULL-terminated array of strings. Use + g_strfreev() to free it.</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a string to split</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="delimiter" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="max_tokens" transfer-ownership="none"> + <doc xml:space="preserve">the maximum number of pieces to split @string into. + If this is less than 1, the string is split completely.</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="strsplit_set" c:identifier="g_strsplit_set" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">a newly-allocated %NULL-terminated array of strings. Use + g_strfreev() to free it.</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">The string to be tokenized</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="delimiters" transfer-ownership="none"> + <doc xml:space="preserve">A nul-terminated string containing bytes that are used + to split the string (it can accept an empty string, which will result + in no string splitting).</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="max_tokens" transfer-ownership="none"> + <doc xml:space="preserve">The maximum number of tokens to split @string into. + If this is less than 1, the string is split completely</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="strstr_len" c:identifier="g_strstr_len"> + <doc xml:space="preserve">Searches the string @haystack for the first occurrence +of the string @needle, limiting the length of the search +to @haystack_len.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to the found occurrence, or + %NULL if not found.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="haystack" transfer-ownership="none"> + <doc xml:space="preserve">a nul-terminated string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="haystack_len" transfer-ownership="none"> + <doc xml:space="preserve">the maximum length of @haystack in bytes. A length of -1 + can be used to mean "search the entire string", like `strstr()`.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="needle" transfer-ownership="none"> + <doc xml:space="preserve">the string to search for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function-macro name="strstrip" c:identifier="g_strstrip" introspectable="0"> + <doc xml:space="preserve">Removes leading and trailing whitespace from a string. +See g_strchomp() and g_strchug().</doc> + <parameters> + <parameter name="string"> + <doc xml:space="preserve">a string to remove the leading and trailing whitespace from</doc> + </parameter> + </parameters> + </function-macro> + <function name="strtod" c:identifier="g_strtod"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #gdouble value.</doc> + <type name="gdouble" c:type="gdouble"/> + </return-value> + <parameters> + <parameter name="nptr" transfer-ownership="none"> + <doc xml:space="preserve">the string to convert to a numeric value.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="endptr" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">if non-%NULL, it returns the + character after the last character used in the conversion.</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </function> + <function name="strup" c:identifier="g_strup" deprecated="1" deprecated-version="2.2"> + <doc xml:space="preserve">Converts a string to upper case.</doc> + <doc-deprecated xml:space="preserve">This function is totally broken for the reasons + discussed in the g_strncasecmp() docs - use g_ascii_strup() + or g_utf8_strup() instead.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the string to convert</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </function> + <function name="strv_contains" c:identifier="g_strv_contains" version="2.44"> + <doc xml:space="preserve">Checks if @strv contains @str. @strv must not be %NULL.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @str is an element of @strv, according to g_str_equal().</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="strv" transfer-ownership="none"> + <doc xml:space="preserve">a %NULL-terminated array of strings</doc> + <type name="utf8" c:type="const gchar* const*"/> + </parameter> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="strv_equal" c:identifier="g_strv_equal" version="2.60"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @strv1 and @strv2 are equal</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="strv1" transfer-ownership="none"> + <doc xml:space="preserve">a %NULL-terminated array of strings</doc> + <type name="utf8" c:type="const gchar* const*"/> + </parameter> + <parameter name="strv2" transfer-ownership="none"> + <doc xml:space="preserve">another %NULL-terminated array of strings</doc> + <type name="utf8" c:type="const gchar* const*"/> + </parameter> + </parameters> + </function> + <function name="strv_get_type" c:identifier="g_strv_get_type"> + <return-value transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </return-value> + </function> + <function name="strv_length" c:identifier="g_strv_length" version="2.6"> + <doc xml:space="preserve">Returns the length of the given %NULL-terminated +string array @str_array. @str_array must not be %NULL.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">length of @str_array.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="str_array" transfer-ownership="none"> + <doc xml:space="preserve">a %NULL-terminated array of strings</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </function> + <function-macro name="test_add" c:identifier="g_test_add" version="2.16" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="testpath"> + <doc xml:space="preserve">The test path for a new test case.</doc> + </parameter> + <parameter name="Fixture"> + <doc xml:space="preserve">The type of a fixture data structure.</doc> + </parameter> + <parameter name="tdata"> + <doc xml:space="preserve">Data argument for the test functions.</doc> + </parameter> + <parameter name="fsetup"> + <doc xml:space="preserve">The function to set up the fixture data.</doc> + </parameter> + <parameter name="ftest"> + <doc xml:space="preserve">The actual test function.</doc> + </parameter> + <parameter name="fteardown"> + <doc xml:space="preserve">The function to tear down the fixture data.</doc> + </parameter> + </parameters> + </function-macro> + <function name="test_add_data_func" c:identifier="g_test_add_data_func" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="testpath" transfer-ownership="none"> + <doc xml:space="preserve">/-separated test case path name for the test.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="test_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Test data argument for the test function.</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="test_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">The test function to invoke for this test.</doc> + <type name="TestDataFunc" c:type="GTestDataFunc"/> + </parameter> + </parameters> + </function> + <function name="test_add_data_func_full" c:identifier="g_test_add_data_func_full" version="2.34"> + <doc xml:space="preserve">Create a new test case, as with g_test_add_data_func(), but freeing +@test_data after the test run is complete.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="testpath" transfer-ownership="none"> + <doc xml:space="preserve">/-separated test case path name for the test.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="test_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Test data argument for the test function.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="test_func" transfer-ownership="none" scope="notified" destroy="3"> + <doc xml:space="preserve">The test function to invoke for this test.</doc> + <type name="TestDataFunc" c:type="GTestDataFunc"/> + </parameter> + <parameter name="data_free_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">#GDestroyNotify for @test_data.</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="test_add_func" c:identifier="g_test_add_func" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="testpath" transfer-ownership="none"> + <doc xml:space="preserve">/-separated test case path name for the test.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="test_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">The test function to invoke for this test.</doc> + <type name="TestFunc" c:type="GTestFunc"/> + </parameter> + </parameters> + </function> + <function name="test_add_vtable" c:identifier="g_test_add_vtable" introspectable="0"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="testpath" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="data_size" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="test_data" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="data_setup" transfer-ownership="none"> + <type name="TestFixtureFunc" c:type="GTestFixtureFunc"/> + </parameter> + <parameter name="data_test" transfer-ownership="none"> + <type name="TestFixtureFunc" c:type="GTestFixtureFunc"/> + </parameter> + <parameter name="data_teardown" transfer-ownership="none"> + <type name="TestFixtureFunc" c:type="GTestFixtureFunc"/> + </parameter> + </parameters> + </function> + <function name="test_assert_expected_messages_internal" c:identifier="g_test_assert_expected_messages_internal"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="domain" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="file" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="line" transfer-ownership="none"> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="func" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="test_bug" c:identifier="g_test_bug" version="2.16"> + <doc xml:space="preserve">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.</doc> + <doc-version xml:space="preserve"> +See also: g_test_summary()</doc-version> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="bug_uri_snippet" transfer-ownership="none"> + <doc xml:space="preserve">Bug specific bug tracker URI portion.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="test_bug_base" c:identifier="g_test_bug_base" version="2.16"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="uri_pattern" transfer-ownership="none"> + <doc xml:space="preserve">the base pattern for bug URIs</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="test_build_filename" c:identifier="g_test_build_filename" version="2.38" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the path of the file, to be freed using g_free()</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="file_type" transfer-ownership="none"> + <doc xml:space="preserve">the type of file (built vs. distributed)</doc> + <type name="TestFileType" c:type="GTestFileType"/> + </parameter> + <parameter name="first_path" transfer-ownership="none"> + <doc xml:space="preserve">the first segment of the pathname</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">%NULL-terminated additional path segments</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="test_create_case" c:identifier="g_test_create_case" version="2.16" introspectable="0"> + <doc xml:space="preserve">Create a new #GTestCase, named @test_name. + +This API is fairly low level, and 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 type is used for +multiple tests. In this cases, g_test_create_case() will be +called with the same type of fixture (the @data_size argument), but varying +@test_name and @data_test arguments.</doc> + <return-value> + <doc xml:space="preserve">a newly allocated #GTestCase.</doc> + <type name="TestCase" c:type="GTestCase*"/> + </return-value> + <parameters> + <parameter name="test_name" transfer-ownership="none"> + <doc xml:space="preserve">the name for the test case</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="data_size" transfer-ownership="none"> + <doc xml:space="preserve">the size of the fixture data structure</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="test_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">test data argument for the test functions</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="data_setup" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">the function to set up the fixture data</doc> + <type name="TestFixtureFunc" c:type="GTestFixtureFunc"/> + </parameter> + <parameter name="data_test" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">the actual test function</doc> + <type name="TestFixtureFunc" c:type="GTestFixtureFunc"/> + </parameter> + <parameter name="data_teardown" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">the function to teardown the fixture data</doc> + <type name="TestFixtureFunc" c:type="GTestFixtureFunc"/> + </parameter> + </parameters> + </function> + <function name="test_create_suite" c:identifier="g_test_create_suite" version="2.16" introspectable="0"> + <doc xml:space="preserve">Create a new test suite with the name @suite_name.</doc> + <return-value> + <doc xml:space="preserve">A newly allocated #GTestSuite instance.</doc> + <type name="TestSuite" c:type="GTestSuite*"/> + </return-value> + <parameters> + <parameter name="suite_name" transfer-ownership="none"> + <doc xml:space="preserve">a name for the suite</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="test_expect_message" c:identifier="g_test_expect_message" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="log_domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the log domain of the message</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="log_level" transfer-ownership="none"> + <doc xml:space="preserve">the log level of the message</doc> + <type name="LogLevelFlags" c:type="GLogLevelFlags"/> + </parameter> + <parameter name="pattern" transfer-ownership="none"> + <doc xml:space="preserve">a glob-style [pattern][glib-Glob-style-pattern-matching]</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="test_fail" c:identifier="g_test_fail" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </function> + <function name="test_failed" c:identifier="g_test_failed" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the test has failed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + </function> + <function name="test_get_dir" c:identifier="g_test_get_dir" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the path of the directory, owned by GLib</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="file_type" transfer-ownership="none"> + <doc xml:space="preserve">the type of file (built vs. distributed)</doc> + <type name="TestFileType" c:type="GTestFileType"/> + </parameter> + </parameters> + </function> + <function name="test_get_filename" c:identifier="g_test_get_filename" version="2.38" introspectable="0"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the path, automatically freed at the end of the testcase</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="file_type" transfer-ownership="none"> + <doc xml:space="preserve">the type of file (built vs. distributed)</doc> + <type name="TestFileType" c:type="GTestFileType"/> + </parameter> + <parameter name="first_path" transfer-ownership="none"> + <doc xml:space="preserve">the first segment of the pathname</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">%NULL-terminated additional path segments</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="test_get_root" c:identifier="g_test_get_root" version="2.16" introspectable="0"> + <doc xml:space="preserve">Get the toplevel test suite for the test path API.</doc> + <return-value> + <doc xml:space="preserve">the toplevel #GTestSuite</doc> + <type name="TestSuite" c:type="GTestSuite*"/> + </return-value> + </function> + <function name="test_incomplete" c:identifier="g_test_incomplete" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="msg" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">explanation</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="test_init" c:identifier="g_test_init" version="2.16" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="argc" transfer-ownership="none"> + <doc xml:space="preserve">Address of the @argc parameter of the main() function. + Changed if any arguments were handled.</doc> + <type name="gint" c:type="int*"/> + </parameter> + <parameter name="argv" transfer-ownership="none"> + <doc xml:space="preserve">Address of the @argv parameter of main(). + Any parameters understood by g_test_init() stripped before return.</doc> + <type name="utf8" c:type="char***"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">%NULL-terminated list of special options, documented below.</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="test_log_set_fatal_handler" c:identifier="g_test_log_set_fatal_handler" version="2.22" introspectable="0"> + <doc xml:space="preserve">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].</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="log_func" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">the log handler function.</doc> + <type name="TestLogFatalFunc" c:type="GTestLogFatalFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data passed to the log handler.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="test_log_type_name" c:identifier="g_test_log_type_name"> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="log_type" transfer-ownership="none"> + <type name="TestLogType" c:type="GTestLogType"/> + </parameter> + </parameters> + </function> + <function name="test_maximized_result" c:identifier="g_test_maximized_result" version="2.16" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="maximized_quantity" transfer-ownership="none"> + <doc xml:space="preserve">the reported value</doc> + <type name="gdouble" c:type="double"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">the format string of the report message</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">arguments to pass to the printf() function</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="test_message" c:identifier="g_test_message" version="2.16" introspectable="0"> + <doc xml:space="preserve">Add a message to the test report.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">the format string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">printf-like arguments to @format</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="test_minimized_result" c:identifier="g_test_minimized_result" version="2.16" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="minimized_quantity" transfer-ownership="none"> + <doc xml:space="preserve">the reported value</doc> + <type name="gdouble" c:type="double"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">the format string of the report message</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">arguments to pass to the printf() function</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="test_queue_destroy" c:identifier="g_test_queue_destroy" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="destroy_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">Destroy callback for teardown phase.</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + <parameter name="destroy_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Destroy callback data.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="test_queue_free" c:identifier="g_test_queue_free" version="2.16"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="gfree_pointer" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the pointer to be stored.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function-macro name="test_queue_unref" c:identifier="g_test_queue_unref" version="2.16" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <parameters> + <parameter name="gobject"> + <doc xml:space="preserve">the object to unref</doc> + </parameter> + </parameters> + </function-macro> + <function name="test_rand_double" c:identifier="g_test_rand_double" version="2.16"> + <doc xml:space="preserve">Get a reproducible random floating point number, +see g_test_rand_int() for details on test case random numbers.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a random number from the seeded random number generator.</doc> + <type name="gdouble" c:type="double"/> + </return-value> + </function> + <function name="test_rand_double_range" c:identifier="g_test_rand_double_range" version="2.16"> + <doc xml:space="preserve">Get a reproducible random floating pointer number out of a specified range, +see g_test_rand_int() for details on test case random numbers.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a number with @range_start <= number < @range_end.</doc> + <type name="gdouble" c:type="double"/> + </return-value> + <parameters> + <parameter name="range_start" transfer-ownership="none"> + <doc xml:space="preserve">the minimum value returned by this function</doc> + <type name="gdouble" c:type="double"/> + </parameter> + <parameter name="range_end" transfer-ownership="none"> + <doc xml:space="preserve">the minimum value not returned by this function</doc> + <type name="gdouble" c:type="double"/> + </parameter> + </parameters> + </function> + <function name="test_rand_int" c:identifier="g_test_rand_int" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a random number from the seeded random number generator.</doc> + <type name="gint32" c:type="gint32"/> + </return-value> + </function> + <function name="test_rand_int_range" c:identifier="g_test_rand_int_range" version="2.16"> + <doc xml:space="preserve">Get a reproducible random integer number out of a specified range, +see g_test_rand_int() for details on test case random numbers.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a number with @begin <= number < @end.</doc> + <type name="gint32" c:type="gint32"/> + </return-value> + <parameters> + <parameter name="begin" transfer-ownership="none"> + <doc xml:space="preserve">the minimum value returned by this function</doc> + <type name="gint32" c:type="gint32"/> + </parameter> + <parameter name="end" transfer-ownership="none"> + <doc xml:space="preserve">the smallest value not to be returned by this function</doc> + <type name="gint32" c:type="gint32"/> + </parameter> + </parameters> + </function> + <function name="test_run" c:identifier="g_test_run" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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()</doc> + <type name="gint" c:type="int"/> + </return-value> + </function> + <function name="test_run_suite" c:identifier="g_test_run_suite" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">0 on success</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <parameter name="suite" transfer-ownership="none"> + <doc xml:space="preserve">a #GTestSuite</doc> + <type name="TestSuite" c:type="GTestSuite*"/> + </parameter> + </parameters> + </function> + <function name="test_set_nonfatal_assertions" c:identifier="g_test_set_nonfatal_assertions" version="2.38"> + <doc xml:space="preserve">Changes the behaviour of the various `g_assert_*()` macros, +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() macros are not +affected by this. + +This function can only be called after g_test_init().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </function> + <function name="test_skip" c:identifier="g_test_skip" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="msg" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">explanation</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="test_subprocess" c:identifier="g_test_subprocess" version="2.38"> + <doc xml:space="preserve">Returns %TRUE (after g_test_init() has been called) if the test +program is running under g_test_trap_subprocess().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the test program is running under +g_test_trap_subprocess().</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + </function> + <function name="test_summary" c:identifier="g_test_summary" version="2.62"> + <doc xml:space="preserve">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."); + + … +} +]|</doc> + <doc-version xml:space="preserve"> +See also: g_test_bug()</doc-version> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="summary" transfer-ownership="none"> + <doc xml:space="preserve">One or two sentences summarising what the test checks, and how it + checks it.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="test_timer_elapsed" c:identifier="g_test_timer_elapsed" version="2.16"> + <doc xml:space="preserve">Get the time since the last start of the timer with g_test_timer_start().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the time since the last start of the timer, as a double</doc> + <type name="gdouble" c:type="double"/> + </return-value> + </function> + <function name="test_timer_last" c:identifier="g_test_timer_last" version="2.16"> + <doc xml:space="preserve">Report the last result of g_test_timer_elapsed().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the last result of g_test_timer_elapsed(), as a double</doc> + <type name="gdouble" c:type="double"/> + </return-value> + </function> + <function name="test_timer_start" c:identifier="g_test_timer_start" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </function> + <function-macro name="test_trap_assert_stderr" c:identifier="g_test_trap_assert_stderr" version="2.16" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="serrpattern"> + <doc xml:space="preserve">a glob-style [pattern][glib-Glob-style-pattern-matching]</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="test_trap_assert_stderr_unmatched" c:identifier="g_test_trap_assert_stderr_unmatched" version="2.16" introspectable="0"> + <doc xml:space="preserve">Assert that the stderr output of the last test subprocess +does not match @serrpattern. See g_test_trap_subprocess().</doc> + <parameters> + <parameter name="serrpattern"> + <doc xml:space="preserve">a glob-style [pattern][glib-Glob-style-pattern-matching]</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="test_trap_assert_stdout" c:identifier="g_test_trap_assert_stdout" version="2.16" introspectable="0"> + <doc xml:space="preserve">Assert that the stdout output of the last test subprocess matches +@soutpattern. See g_test_trap_subprocess().</doc> + <parameters> + <parameter name="soutpattern"> + <doc xml:space="preserve">a glob-style [pattern][glib-Glob-style-pattern-matching]</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="test_trap_assert_stdout_unmatched" c:identifier="g_test_trap_assert_stdout_unmatched" version="2.16" introspectable="0"> + <doc xml:space="preserve">Assert that the stdout output of the last test subprocess +does not match @soutpattern. See g_test_trap_subprocess().</doc> + <parameters> + <parameter name="soutpattern"> + <doc xml:space="preserve">a glob-style [pattern][glib-Glob-style-pattern-matching]</doc> + </parameter> + </parameters> + </function-macro> + <function name="test_trap_assertions" c:identifier="g_test_trap_assertions"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="domain" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="file" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="line" transfer-ownership="none"> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="func" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="assertion_flags" transfer-ownership="none"> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="pattern" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="test_trap_fork" c:identifier="g_test_trap_fork" version="2.16" deprecated="1"> + <doc xml:space="preserve">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*"); + } +]|</doc> + <doc-deprecated xml:space="preserve">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.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE for the forked child and %FALSE for the executing parent process.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="usec_timeout" transfer-ownership="none"> + <doc xml:space="preserve">Timeout for the forked test in micro seconds.</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="test_trap_flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags to modify forking behaviour.</doc> + <type name="TestTrapFlags" c:type="GTestTrapFlags"/> + </parameter> + </parameters> + </function> + <function name="test_trap_has_passed" c:identifier="g_test_trap_has_passed" version="2.16"> + <doc xml:space="preserve">Check the result of the last g_test_trap_subprocess() call.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the last test subprocess terminated successfully.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + </function> + <function name="test_trap_reached_timeout" c:identifier="g_test_trap_reached_timeout" version="2.16"> + <doc xml:space="preserve">Check the result of the last g_test_trap_subprocess() call.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the last test subprocess got killed due to a timeout.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + </function> + <function name="test_trap_subprocess" c:identifier="g_test_trap_subprocess" version="2.38"> + <doc xml:space="preserve">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 (); + } +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="test_path" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Test to run in a subprocess</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="usec_timeout" transfer-ownership="none"> + <doc xml:space="preserve">Timeout for the subprocess test in micro seconds.</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="test_flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags to modify subprocess behaviour.</doc> + <type name="TestSubprocessFlags" c:type="GTestSubprocessFlags"/> + </parameter> + </parameters> + </function> + <docsection name="testing"> + <doc xml:space="preserve">GLib provides a framework for writing and maintaining unit tests +in parallel to the code they are testing. The API is designed according +to established concepts found in the other test frameworks (JUnit, NUnit, +RUnit), which in turn is based on smalltalk unit testing concepts. + +- Test case: Tests (test methods) are grouped together with their + fixture into test cases. + +- Fixture: A test fixture consists of fixture data and setup and + teardown methods to establish the environment for the test + functions. We use fresh fixtures, i.e. fixtures are newly set + up and torn down around each test invocation to avoid dependencies + between tests. + +- Test suite: Test cases can be grouped into test suites, to allow + subsets of the available tests to be run. Test suites can be + grouped into other test suites as well. + +The API is designed to handle creation and registration of test suites +and test cases implicitly. A simple call like +|[<!-- language="C" --> + g_test_add_func ("/misc/assertions", test_assertions); +]| +creates a test suite called "misc" with a single test case named +"assertions", which consists of running the test_assertions function. + +In addition to the traditional g_assert_true(), the test framework provides +an extended set of assertions for comparisons: g_assert_cmpfloat(), +g_assert_cmpfloat_with_epsilon(), g_assert_cmpint(), g_assert_cmpuint(), +g_assert_cmphex(), g_assert_cmpstr(), g_assert_cmpmem() and +g_assert_cmpvariant(). The +advantage of these variants over plain g_assert_true() is that the assertion +messages can be more elaborate, and include the values of the compared +entities. + +Note that g_assert() should not be used in unit tests, since it is a no-op +when compiling with `G_DISABLE_ASSERT`. Use g_assert() in production code, +and g_assert_true() in unit tests. + +A full example of creating a test suite with two tests using fixtures: +|[<!-- language="C" --> +#include <glib.h> +#include <locale.h> + +typedef struct { + MyObject *obj; + OtherObject *helper; +} MyObjectFixture; + +static void +my_object_fixture_set_up (MyObjectFixture *fixture, + gconstpointer user_data) +{ + fixture->obj = my_object_new (); + my_object_set_prop1 (fixture->obj, "some-value"); + my_object_do_some_complex_setup (fixture->obj, user_data); + + fixture->helper = other_object_new (); +} + +static void +my_object_fixture_tear_down (MyObjectFixture *fixture, + gconstpointer user_data) +{ + g_clear_object (&fixture->helper); + g_clear_object (&fixture->obj); +} + +static void +test_my_object_test1 (MyObjectFixture *fixture, + gconstpointer user_data) +{ + g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "initial-value"); +} + +static void +test_my_object_test2 (MyObjectFixture *fixture, + gconstpointer user_data) +{ + my_object_do_some_work_using_helper (fixture->obj, fixture->helper); + g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "updated-value"); +} + +int +main (int argc, char *argv[]) +{ + setlocale (LC_ALL, ""); + + g_test_init (&argc, &argv, NULL); + + // Define the tests. + g_test_add ("/my-object/test1", MyObjectFixture, "some-user-data", + my_object_fixture_set_up, test_my_object_test1, + my_object_fixture_tear_down); + g_test_add ("/my-object/test2", MyObjectFixture, "some-user-data", + my_object_fixture_set_up, test_my_object_test2, + my_object_fixture_tear_down); + + return g_test_run (); +} +]| + +### Integrating GTest in your project + +If you are using the [Meson](http://mesonbuild.com) build system, you will +typically use the provided `test()` primitive to call the test binaries, +e.g.: + +|[<!-- language="plain" --> + test( + 'foo', + executable('foo', 'foo.c', dependencies: deps), + env: [ + 'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()), + 'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()), + ], + ) + + test( + 'bar', + executable('bar', 'bar.c', dependencies: deps), + env: [ + 'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()), + 'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()), + ], + ) +]| + +If you are using Autotools, you're strongly encouraged to use the Automake +[TAP](https://testanything.org/) harness; GLib provides template files for +easily integrating with it: + + - [glib-tap.mk](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/glib-tap.mk) + - [tap-test](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/tap-test) + - [tap-driver.sh](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/tap-driver.sh) + +You can copy these files in your own project's root directory, and then +set up your `Makefile.am` file to reference them, for instance: + +|[<!-- language="plain" --> +include $(top_srcdir)/glib-tap.mk + +# test binaries +test_programs = \ + foo \ + bar + +# data distributed in the tarball +dist_test_data = \ + foo.data.txt \ + bar.data.txt + +# data not distributed in the tarball +test_data = \ + blah.data.txt +]| + +Make sure to distribute the TAP files, using something like the following +in your top-level `Makefile.am`: + +|[<!-- language="plain" --> +EXTRA_DIST += \ + tap-driver.sh \ + tap-test +]| + +`glib-tap.mk` will be distributed implicitly due to being included in a +`Makefile.am`. All three files should be added to version control. + +If you don't have access to the Autotools TAP harness, you can use the +[gtester][gtester] and [gtester-report][gtester-report] tools, and use +the [glib.mk](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/glib.mk) +Automake template provided by GLib. Note, however, that since GLib 2.62, +[gtester][gtester] and [gtester-report][gtester-report] have been deprecated +in favour of using TAP. The `--tap` argument to tests is enabled by default +as of GLib 2.62.</doc> + </docsection> + <function name="thread_error_quark" c:identifier="g_thread_error_quark" moved-to="Thread.error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="thread_exit" c:identifier="g_thread_exit" moved-to="Thread.exit"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="retval" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the return value of this thread</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="thread_pool_get_max_idle_time" c:identifier="g_thread_pool_get_max_idle_time" moved-to="ThreadPool.get_max_idle_time" version="2.10"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the maximum @interval (milliseconds) to wait + for new tasks in the thread pool before stopping the + thread</doc> + <type name="guint" c:type="guint"/> + </return-value> + </function> + <function name="thread_pool_get_max_unused_threads" c:identifier="g_thread_pool_get_max_unused_threads" moved-to="ThreadPool.get_max_unused_threads"> + <doc xml:space="preserve">Returns the maximal allowed number of unused threads.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the maximal number of unused threads</doc> + <type name="gint" c:type="gint"/> + </return-value> + </function> + <function name="thread_pool_get_num_unused_threads" c:identifier="g_thread_pool_get_num_unused_threads" moved-to="ThreadPool.get_num_unused_threads"> + <doc xml:space="preserve">Returns the number of currently unused threads.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of currently unused threads</doc> + <type name="guint" c:type="guint"/> + </return-value> + </function> + <function name="thread_pool_set_max_idle_time" c:identifier="g_thread_pool_set_max_idle_time" moved-to="ThreadPool.set_max_idle_time" version="2.10"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="interval" transfer-ownership="none"> + <doc xml:space="preserve">the maximum @interval (in milliseconds) + a thread can be idle</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="thread_pool_set_max_unused_threads" c:identifier="g_thread_pool_set_max_unused_threads" moved-to="ThreadPool.set_max_unused_threads"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="max_threads" transfer-ownership="none"> + <doc xml:space="preserve">maximal number of unused threads</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="thread_pool_stop_unused_threads" c:identifier="g_thread_pool_stop_unused_threads" moved-to="ThreadPool.stop_unused_threads"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </function> + <docsection name="thread_pools"> + <doc xml:space="preserve">Sometimes you wish to asynchronously fork out the execution of work +and continue working in your own thread. If that will happen often, +the overhead of starting and destroying a thread each time might be +too high. In such cases reusing already started threads seems like a +good idea. And it indeed is, but implementing this can be tedious +and error-prone. + +Therefore GLib provides thread pools for your convenience. An added +advantage is, that the threads can be shared between the different +subsystems of your program, when they are using GLib. + +To create a new thread pool, you use g_thread_pool_new(). +It is destroyed by g_thread_pool_free(). + +If you want to execute a certain task within a thread pool, +you call g_thread_pool_push(). + +To get the current number of running threads you call +g_thread_pool_get_num_threads(). To get the number of still +unprocessed tasks you call g_thread_pool_unprocessed(). To control +the maximal number of threads for a thread pool, you use +g_thread_pool_get_max_threads() and g_thread_pool_set_max_threads(). + +Finally you can control the number of unused threads, that are kept +alive by GLib for future use. The current number can be fetched with +g_thread_pool_get_num_unused_threads(). The maximal number can be +controlled by g_thread_pool_get_max_unused_threads() and +g_thread_pool_set_max_unused_threads(). All currently unused threads +can be stopped by calling g_thread_pool_stop_unused_threads().</doc> + </docsection> + <function name="thread_self" c:identifier="g_thread_self" moved-to="Thread.self"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GThread representing the current thread</doc> + <type name="Thread" c:type="GThread*"/> + </return-value> + </function> + <function name="thread_yield" c:identifier="g_thread_yield" moved-to="Thread.yield"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </function> + <docsection name="threads"> + <doc xml:space="preserve">Threads act almost like processes, but unlike processes all threads +of one process share the same memory. This is good, as it provides +easy communication between the involved threads via this shared +memory, and it is bad, because strange things (so called +"Heisenbugs") might happen if the program is not carefully designed. +In particular, due to the concurrent nature of threads, no +assumptions on the order of execution of code running in different +threads can be made, unless order is explicitly forced by the +programmer through synchronization primitives. + +The aim of the thread-related functions in GLib is to provide a +portable means for writing multi-threaded software. There are +primitives for mutexes to protect the access to portions of memory +(#GMutex, #GRecMutex and #GRWLock). There is a facility to use +individual bits for locks (g_bit_lock()). There are primitives +for condition variables to allow synchronization of threads (#GCond). +There are primitives for thread-private data - data that every +thread has a private instance of (#GPrivate). There are facilities +for one-time initialization (#GOnce, g_once_init_enter()). Finally, +there are primitives to create and manage threads (#GThread). + +The GLib threading system used to be initialized with g_thread_init(). +This is no longer necessary. Since version 2.32, the GLib threading +system is automatically initialized at the start of your program, +and all thread-creation functions and synchronization primitives +are available right away. + +Note that it is not safe to assume that your program has no threads +even if you don't call g_thread_new() yourself. GLib and GIO can +and will create threads for their own purposes in some cases, such +as when using g_unix_signal_source_new() or when using GDBus. + +Originally, UNIX did not have threads, and therefore some traditional +UNIX APIs are problematic in threaded programs. Some notable examples +are + +- C library functions that return data in statically allocated + buffers, such as strtok() or strerror(). For many of these, + there are thread-safe variants with a _r suffix, or you can + look at corresponding GLib APIs (like g_strsplit() or g_strerror()). + +- The functions setenv() and unsetenv() manipulate the process + environment in a not thread-safe way, and may interfere with getenv() + calls in other threads. Note that getenv() calls may be hidden behind + other APIs. For example, GNU gettext() calls getenv() under the + covers. In general, it is best to treat the environment as readonly. + If you absolutely have to modify the environment, do it early in + main(), when no other threads are around yet. + +- The setlocale() function changes the locale for the entire process, + affecting all threads. Temporary changes to the locale are often made + to change the behavior of string scanning or formatting functions + like scanf() or printf(). GLib offers a number of string APIs + (like g_ascii_formatd() or g_ascii_strtod()) that can often be + used as an alternative. Or you can use the uselocale() function + to change the locale only for the current thread. + +- The fork() function only takes the calling thread into the child's + copy of the process image. If other threads were executing in critical + sections they could have left mutexes locked which could easily + cause deadlocks in the new child. For this reason, you should + call exit() or exec() as soon as possible in the child and only + make signal-safe library calls before that. + +- The daemon() function uses fork() in a way contrary to what is + described above. It should not be used with GLib programs. + +GLib itself is internally completely thread-safe (all global data is +automatically locked), but individual data structure instances are +not automatically locked for performance reasons. For example, +you must coordinate accesses to the same #GHashTable from multiple +threads. The two notable exceptions from this rule are #GMainLoop +and #GAsyncQueue, which are thread-safe and need no further +application-level locking to be accessed from multiple threads. +Most refcounting functions such as g_object_ref() are also thread-safe. + +A common use for #GThreads is to move a long-running blocking operation out +of the main thread and into a worker thread. For GLib functions, such as +single GIO operations, this is not necessary, and complicates the code. +Instead, the `…_async()` version of the function should be used from the main +thread, eliminating the need for locking and synchronisation between multiple +threads. If an operation does need to be moved to a worker thread, consider +using g_task_run_in_thread(), or a #GThreadPool. #GThreadPool is often a +better choice than #GThread, as it handles thread reuse and task queueing; +#GTask uses this internally. + +However, if multiple blocking operations need to be performed in sequence, +and it is not possible to use #GTask for them, moving them to a worker thread +can clarify the code.</doc> + </docsection> + <function name="time_val_from_iso8601" c:identifier="g_time_val_from_iso8601" moved-to="TimeVal.from_iso8601" version="2.12" deprecated="1" deprecated-version="2.62"> + <doc xml:space="preserve">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); +]|</doc> + <doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use + g_date_time_new_from_iso8601() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the conversion was successful.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="iso_date" transfer-ownership="none"> + <doc xml:space="preserve">an ISO 8601 encoded date string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="time_" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeVal</doc> + <type name="TimeVal" c:type="GTimeVal*"/> + </parameter> + </parameters> + </function> + <function name="timeout_add" c:identifier="g_timeout_add" shadowed-by="timeout_add_full" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ID (greater than 0) of the event source.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="interval" transfer-ownership="none"> + <doc xml:space="preserve">the time between calls to the function, in milliseconds + (1/1000ths of a second)</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="function" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">function to call</doc> + <type name="SourceFunc" c:type="GSourceFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="timeout_add_full" c:identifier="g_timeout_add_full" shadows="timeout_add"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ID (greater than 0) of the event source.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="priority" transfer-ownership="none"> + <doc xml:space="preserve">the priority of the timeout source. Typically this will be in + the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="interval" transfer-ownership="none"> + <doc xml:space="preserve">the time between calls to the function, in milliseconds + (1/1000ths of a second)</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="function" transfer-ownership="none" scope="notified" closure="3" destroy="4"> + <doc xml:space="preserve">function to call</doc> + <type name="SourceFunc" c:type="GSourceFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">function to call when the timeout is removed, or %NULL</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="timeout_add_seconds" c:identifier="g_timeout_add_seconds" shadowed-by="timeout_add_seconds_full" version="2.14" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ID (greater than 0) of the event source.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="interval" transfer-ownership="none"> + <doc xml:space="preserve">the time between calls to the function, in seconds</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="function" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">function to call</doc> + <type name="SourceFunc" c:type="GSourceFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="timeout_add_seconds_full" c:identifier="g_timeout_add_seconds_full" shadows="timeout_add_seconds" version="2.14"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ID (greater than 0) of the event source.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="priority" transfer-ownership="none"> + <doc xml:space="preserve">the priority of the timeout source. Typically this will be in + the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="interval" transfer-ownership="none"> + <doc xml:space="preserve">the time between calls to the function, in seconds</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="function" transfer-ownership="none" scope="notified" closure="3" destroy="4"> + <doc xml:space="preserve">function to call</doc> + <type name="SourceFunc" c:type="GSourceFunc"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">function to call when the timeout is removed, or %NULL</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="timeout_source_new" c:identifier="g_timeout_source_new"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the newly-created timeout source</doc> + <type name="Source" c:type="GSource*"/> + </return-value> + <parameters> + <parameter name="interval" transfer-ownership="none"> + <doc xml:space="preserve">the timeout interval in milliseconds.</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="timeout_source_new_seconds" c:identifier="g_timeout_source_new_seconds" version="2.14"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the newly-created timeout source</doc> + <type name="Source" c:type="GSource*"/> + </return-value> + <parameters> + <parameter name="interval" transfer-ownership="none"> + <doc xml:space="preserve">the timeout interval in seconds</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <docsection name="timers"> + <doc xml:space="preserve">#GTimer records a start time, and counts microseconds elapsed since +that time. This is done somewhat differently on different platforms, +and can be tricky to get exactly right, so #GTimer provides a +portable/convenient interface.</doc> + </docsection> + <docsection name="timezone"> + <doc xml:space="preserve">#GTimeZone is a structure that represents a time zone, at no +particular point in time. It is refcounted and immutable. + +Each time zone has an identifier (for example, ‘Europe/London’) which is +platform dependent. See g_time_zone_new() for information on the identifier +formats. The identifier of a time zone can be retrieved using +g_time_zone_get_identifier(). + +A time zone contains a number of intervals. Each interval has +an abbreviation to describe it (for example, ‘PDT’), an offset to UTC and a +flag indicating if the daylight savings time is in effect during that +interval. A time zone always has at least one interval — interval 0. Note +that interval abbreviations are not the same as time zone identifiers +(apart from ‘UTC’), and cannot be passed to g_time_zone_new(). + +Every UTC time is contained within exactly one interval, but a given +local time may be contained within zero, one or two intervals (due to +incontinuities associated with daylight savings time). + +An interval may refer to a specific period of time (eg: the duration +of daylight savings time during 2010) or it may refer to many periods +of time that share the same properties (eg: all periods of daylight +savings time). It is also possible (usually for political reasons) +that some properties (like the abbreviation) change between intervals +without other properties changing. + +#GTimeZone is available since GLib 2.26.</doc> + </docsection> + <docsection name="trash_stack"> + <doc xml:space="preserve">A #GTrashStack is an efficient way to keep a stack of unused allocated +memory chunks. Each memory chunk is required to be large enough to hold +a #gpointer. This allows the stack to be maintained without any space +overhead, since the stack pointers can be stored inside the memory chunks. + +There is no function to create a #GTrashStack. A %NULL #GTrashStack* +is a perfectly valid empty stack. + +There is no longer any good reason to use #GTrashStack. If you have +extra pieces of memory, free() them and allocate them again later.</doc> + </docsection> + <function name="trash_stack_height" c:identifier="g_trash_stack_height" moved-to="TrashStack.height" deprecated="1" deprecated-version="2.48"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the height of the stack</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="stack_p" transfer-ownership="none"> + <doc xml:space="preserve">a #GTrashStack</doc> + <type name="TrashStack" c:type="GTrashStack**"/> + </parameter> + </parameters> + </function> + <function name="trash_stack_peek" c:identifier="g_trash_stack_peek" moved-to="TrashStack.peek" deprecated="1" deprecated-version="2.48"> + <doc xml:space="preserve">Returns the element at the top of a #GTrashStack +which may be %NULL.</doc> + <doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the element at the top of the stack</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="stack_p" transfer-ownership="none"> + <doc xml:space="preserve">a #GTrashStack</doc> + <type name="TrashStack" c:type="GTrashStack**"/> + </parameter> + </parameters> + </function> + <function name="trash_stack_pop" c:identifier="g_trash_stack_pop" moved-to="TrashStack.pop" deprecated="1" deprecated-version="2.48"> + <doc xml:space="preserve">Pops a piece of memory off a #GTrashStack.</doc> + <doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the element at the top of the stack</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="stack_p" transfer-ownership="none"> + <doc xml:space="preserve">a #GTrashStack</doc> + <type name="TrashStack" c:type="GTrashStack**"/> + </parameter> + </parameters> + </function> + <function name="trash_stack_push" c:identifier="g_trash_stack_push" moved-to="TrashStack.push" deprecated="1" deprecated-version="2.48"> + <doc xml:space="preserve">Pushes a piece of memory onto a #GTrashStack.</doc> + <doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="stack_p" transfer-ownership="none"> + <doc xml:space="preserve">a #GTrashStack</doc> + <type name="TrashStack" c:type="GTrashStack**"/> + </parameter> + <parameter name="data_p" transfer-ownership="none"> + <doc xml:space="preserve">the piece of memory to push on the stack</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <docsection name="trees-binary"> + <doc xml:space="preserve">The #GTree structure and its associated functions provide a sorted +collection of key/value pairs optimized for searching and traversing +in order. This means that most of the operations (access, search, +insertion, deletion, ...) on #GTree are O(log(n)) in average and O(n) +in worst case for time complexity. But, note that maintaining a +balanced sorted #GTree of n elements is done in time O(n log(n)). + +To create a new #GTree use g_tree_new(). + +To insert a key/value pair into a #GTree use g_tree_insert() +(O(n log(n))). + +To remove a key/value pair use g_tree_remove() (O(n log(n))). + +To look up the value corresponding to a given key, use +g_tree_lookup() and g_tree_lookup_extended(). + +To find out the number of nodes in a #GTree, use g_tree_nnodes(). To +get the height of a #GTree, use g_tree_height(). + +To traverse a #GTree, calling a function for each node visited in +the traversal, use g_tree_foreach(). + +To destroy a #GTree, use g_tree_destroy().</doc> + </docsection> + <docsection name="trees-nary"> + <doc xml:space="preserve">The #GNode struct and its associated functions provide a N-ary tree +data structure, where nodes in the tree can contain arbitrary data. + +To create a new tree use g_node_new(). + +To insert a node into a tree use g_node_insert(), +g_node_insert_before(), g_node_append() and g_node_prepend(). + +To create a new node and insert it into a tree use +g_node_insert_data(), g_node_insert_data_after(), +g_node_insert_data_before(), g_node_append_data() +and g_node_prepend_data(). + +To reverse the children of a node use g_node_reverse_children(). + +To find a node use g_node_get_root(), g_node_find(), +g_node_find_child(), g_node_child_index(), g_node_child_position(), +g_node_first_child(), g_node_last_child(), g_node_nth_child(), +g_node_first_sibling(), g_node_prev_sibling(), g_node_next_sibling() +or g_node_last_sibling(). + +To get information about a node or tree use G_NODE_IS_LEAF(), +G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(), +g_node_n_children(), g_node_is_ancestor() or g_node_max_height(). + +To traverse a tree, calling a function for each node visited in the +traversal, use g_node_traverse() or g_node_children_foreach(). + +To remove a node or subtree from a tree use g_node_unlink() or +g_node_destroy().</doc> + </docsection> + <function name="try_malloc" c:identifier="g_try_malloc"> + <doc xml:space="preserve">Attempts to allocate @n_bytes, and returns %NULL on failure. +Contrast with g_malloc(), which aborts the program on failure.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the allocated memory, or %NULL.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="n_bytes" transfer-ownership="none"> + <doc xml:space="preserve">number of bytes to allocate.</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="try_malloc0" c:identifier="g_try_malloc0" version="2.8"> + <doc xml:space="preserve">Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on +failure. Contrast with g_malloc0(), which aborts the program on failure.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the allocated memory, or %NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="n_bytes" transfer-ownership="none"> + <doc xml:space="preserve">number of bytes to allocate</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="try_malloc0_n" c:identifier="g_try_malloc0_n" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the allocated memory, or %NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="n_blocks" transfer-ownership="none"> + <doc xml:space="preserve">the number of blocks to allocate</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="n_block_bytes" transfer-ownership="none"> + <doc xml:space="preserve">the size of each block in bytes</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="try_malloc_n" c:identifier="g_try_malloc_n" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the allocated memory, or %NULL.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="n_blocks" transfer-ownership="none"> + <doc xml:space="preserve">the number of blocks to allocate</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="n_block_bytes" transfer-ownership="none"> + <doc xml:space="preserve">the size of each block in bytes</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function-macro name="try_new" c:identifier="g_try_new" version="2.8" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="struct_type"> + <doc xml:space="preserve">the type of the elements to allocate</doc> + </parameter> + <parameter name="n_structs"> + <doc xml:space="preserve">the number of elements to allocate</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="try_new0" c:identifier="g_try_new0" version="2.8" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="struct_type"> + <doc xml:space="preserve">the type of the elements to allocate</doc> + </parameter> + <parameter name="n_structs"> + <doc xml:space="preserve">the number of elements to allocate</doc> + </parameter> + </parameters> + </function-macro> + <function name="try_realloc" c:identifier="g_try_realloc"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the allocated memory, or %NULL.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="mem" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">previously-allocated memory, or %NULL.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_bytes" transfer-ownership="none"> + <doc xml:space="preserve">number of bytes to allocate.</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="try_realloc_n" c:identifier="g_try_realloc_n" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the allocated memory, or %NULL.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="mem" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">previously-allocated memory, or %NULL.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_blocks" transfer-ownership="none"> + <doc xml:space="preserve">the number of blocks to allocate</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="n_block_bytes" transfer-ownership="none"> + <doc xml:space="preserve">the size of each block in bytes</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function-macro name="try_renew" c:identifier="g_try_renew" version="2.8" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="struct_type"> + <doc xml:space="preserve">the type of the elements to allocate</doc> + </parameter> + <parameter name="mem"> + <doc xml:space="preserve">the currently allocated memory</doc> + </parameter> + <parameter name="n_structs"> + <doc xml:space="preserve">the number of elements to allocate</doc> + </parameter> + </parameters> + </function-macro> + <docsection name="type_conversion"> + <doc xml:space="preserve">Many times GLib, GTK+, and other libraries allow you to pass "user +data" to a callback, in the form of a void pointer. From time to time +you want to pass an integer instead of a pointer. You could allocate +an integer, with something like: +|[<!-- language="C" --> + int *ip = g_new (int, 1); + *ip = 42; +]| +But this is inconvenient, and it's annoying to have to free the +memory at some later time. + +Pointers are always at least 32 bits in size (on all platforms GLib +intends to support). Thus you can store at least 32-bit integer values +in a pointer value. Naively, you might try this, but it's incorrect: +|[<!-- language="C" --> + gpointer p; + int i; + p = (void*) 42; + i = (int) p; +]| +Again, that example was not correct, don't copy it. +The problem is that on some systems you need to do this: +|[<!-- language="C" --> + gpointer p; + int i; + p = (void*) (long) 42; + i = (int) (long) p; +]| +The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care +to do the right thing on every platform. + +Warning: You may not store pointers in integers. This is not +portable in any way, shape or form. These macros only allow storing +integers in pointers, and only preserve 32 bits of the integer; values +outside the range of a 32-bit integer will be mangled.</doc> + </docsection> + <docsection name="types"> + <doc xml:space="preserve">GLib defines a number of commonly used types, which can be divided +into several groups: +- New types which are not part of standard C (but are defined in + various C standard library header files) — #gboolean, #gssize. +- Integer types which are guaranteed to be the same size across + all platforms — #gint8, #guint8, #gint16, #guint16, #gint32, + #guint32, #gint64, #guint64. +- Types which are easier to use than their standard C counterparts - + #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong. +- Types which correspond exactly to standard C types, but are + included for completeness — #gchar, #gint, #gshort, #glong, + #gfloat, #gdouble. +- Types which correspond exactly to standard C99 types, but are available + to use even if your compiler does not support C99 — #gsize, #goffset, + #gintptr, #guintptr. + +GLib also defines macros for the limits of some of the standard +integer and floating point types, as well as macros for suitable +printf() formats for these types. + +Note that depending on the platform and build configuration, the format +macros might not be compatible with the system provided printf() function, +because GLib might use a different printf() implementation internally. +The format macros will always work with GLib API (like g_print()), and with +any C99 compatible printf() implementation.</doc> + </docsection> + <function name="ucs4_to_utf16" c:identifier="g_ucs4_to_utf16" throws="1"> + <doc xml:space="preserve">Convert a string from UCS-4 to UTF-16. A 0 character will be +added to the result after the converted text.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="guint16" c:type="gunichar2*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UCS-4 encoded string</doc> + <type name="gunichar" c:type="const gunichar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the maximum length (number of characters) of @str to use. + If @len < 0, then the string is nul-terminated.</doc> + <type name="glong" c:type="glong"/> + </parameter> + <parameter name="items_read" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store number of + bytes read, or %NULL. If an error occurs then the index of the invalid + input is stored here.</doc> + <type name="glong" c:type="glong*"/> + </parameter> + <parameter name="items_written" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store number + of #gunichar2 written, or %NULL. The value stored here does not include + the trailing 0.</doc> + <type name="glong" c:type="glong*"/> + </parameter> + </parameters> + </function> + <function name="ucs4_to_utf8" c:identifier="g_ucs4_to_utf8" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UCS-4 encoded string</doc> + <type name="gunichar" c:type="const gunichar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the maximum length (number of characters) of @str to use. + If @len < 0, then the string is nul-terminated.</doc> + <type name="glong" c:type="glong"/> + </parameter> + <parameter name="items_read" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store number of + characters read, or %NULL.</doc> + <type name="glong" c:type="glong*"/> + </parameter> + <parameter name="items_written" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store number + of bytes written or %NULL. The value here stored does not include the + trailing 0 byte.</doc> + <type name="glong" c:type="glong*"/> + </parameter> + </parameters> + </function> + <function-macro name="uint64_checked_add" c:identifier="g_uint64_checked_add" version="2.48" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="dest"> + <doc xml:space="preserve">a pointer to the #guint64 destination</doc> + </parameter> + <parameter name="a"> + <doc xml:space="preserve">the #guint64 left operand</doc> + </parameter> + <parameter name="b"> + <doc xml:space="preserve">the #guint64 right operand</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="uint64_checked_mul" c:identifier="g_uint64_checked_mul" version="2.48" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="dest"> + <doc xml:space="preserve">a pointer to the #guint64 destination</doc> + </parameter> + <parameter name="a"> + <doc xml:space="preserve">the #guint64 left operand</doc> + </parameter> + <parameter name="b"> + <doc xml:space="preserve">the #guint64 right operand</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="uint_checked_add" c:identifier="g_uint_checked_add" version="2.48" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="dest"> + <doc xml:space="preserve">a pointer to the #guint destination</doc> + </parameter> + <parameter name="a"> + <doc xml:space="preserve">the #guint left operand</doc> + </parameter> + <parameter name="b"> + <doc xml:space="preserve">the #guint right operand</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="uint_checked_mul" c:identifier="g_uint_checked_mul" version="2.48" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="dest"> + <doc xml:space="preserve">a pointer to the #guint destination</doc> + </parameter> + <parameter name="a"> + <doc xml:space="preserve">the #guint left operand</doc> + </parameter> + <parameter name="b"> + <doc xml:space="preserve">the #guint right operand</doc> + </parameter> + </parameters> + </function-macro> + <function name="unichar_break_type" c:identifier="g_unichar_break_type"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the break type of @c</doc> + <type name="UnicodeBreakType" c:type="GUnicodeBreakType"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_combining_class" c:identifier="g_unichar_combining_class" version="2.14"> + <doc xml:space="preserve">Determines the canonical combining class of a Unicode character.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the combining class of the character</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="uc" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_compose" c:identifier="g_unichar_compose" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the characters could be composed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="a" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + <parameter name="b" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + <parameter name="ch" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">return location for the composed character</doc> + <type name="gunichar" c:type="gunichar*"/> + </parameter> + </parameters> + </function> + <function name="unichar_decompose" c:identifier="g_unichar_decompose" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the character could be decomposed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="ch" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + <parameter name="a" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">return location for the first component of @ch</doc> + <type name="gunichar" c:type="gunichar*"/> + </parameter> + <parameter name="b" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">return location for the second component of @ch</doc> + <type name="gunichar" c:type="gunichar*"/> + </parameter> + </parameters> + </function> + <function name="unichar_digit_value" c:identifier="g_unichar_digit_value"> + <doc xml:space="preserve">Determines the numeric value of a character as a decimal +digit.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">If @c is a decimal digit (according to +g_unichar_isdigit()), its numeric value. Otherwise, -1.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_fully_decompose" c:identifier="g_unichar_fully_decompose" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the length of the full decomposition.</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="ch" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character.</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + <parameter name="compat" transfer-ownership="none"> + <doc xml:space="preserve">whether perform canonical or compatibility decomposition</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="result" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store decomposed result, or %NULL</doc> + <type name="gunichar" c:type="gunichar*"/> + </parameter> + <parameter name="result_len" transfer-ownership="none"> + <doc xml:space="preserve">length of @result</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="unichar_get_mirror_char" c:identifier="g_unichar_get_mirror_char" version="2.4"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @ch has a mirrored character, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="ch" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + <parameter name="mirrored_ch" transfer-ownership="none"> + <doc xml:space="preserve">location to store the mirrored character</doc> + <type name="gunichar" c:type="gunichar*"/> + </parameter> + </parameters> + </function> + <function name="unichar_get_script" c:identifier="g_unichar_get_script" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GUnicodeScript for the character.</doc> + <type name="UnicodeScript" c:type="GUnicodeScript"/> + </return-value> + <parameters> + <parameter name="ch" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_isalnum" c:identifier="g_unichar_isalnum"> + <doc xml:space="preserve">Determines whether a character is alphanumeric. +Given some UTF-8 text, obtain a character value +with g_utf8_get_char().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @c is an alphanumeric character</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_isalpha" c:identifier="g_unichar_isalpha"> + <doc xml:space="preserve">Determines whether a character is alphabetic (i.e. a letter). +Given some UTF-8 text, obtain a character value with +g_utf8_get_char().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @c is an alphabetic character</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_iscntrl" c:identifier="g_unichar_iscntrl"> + <doc xml:space="preserve">Determines whether a character is a control character. +Given some UTF-8 text, obtain a character value with +g_utf8_get_char().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @c is a control character</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_isdefined" c:identifier="g_unichar_isdefined"> + <doc xml:space="preserve">Determines if a given character is assigned in the Unicode +standard.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the character has an assigned value</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_isdigit" c:identifier="g_unichar_isdigit"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @c is a digit</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_isgraph" c:identifier="g_unichar_isgraph"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @c is printable unless it's a space</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_islower" c:identifier="g_unichar_islower"> + <doc xml:space="preserve">Determines whether a character is a lowercase letter. +Given some UTF-8 text, obtain a character value with +g_utf8_get_char().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @c is a lowercase letter</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_ismark" c:identifier="g_unichar_ismark" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @c is a mark character</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_isprint" c:identifier="g_unichar_isprint"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @c is printable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_ispunct" c:identifier="g_unichar_ispunct"> + <doc xml:space="preserve">Determines whether a character is punctuation or a symbol. +Given some UTF-8 text, obtain a character value with +g_utf8_get_char().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @c is a punctuation or symbol character</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_isspace" c:identifier="g_unichar_isspace"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @c is a space character</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_istitle" c:identifier="g_unichar_istitle"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the character is titlecase</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_isupper" c:identifier="g_unichar_isupper"> + <doc xml:space="preserve">Determines if a character is uppercase.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @c is an uppercase character</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_iswide" c:identifier="g_unichar_iswide"> + <doc xml:space="preserve">Determines if a character is typically rendered in a double-width +cell.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the character is wide</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_iswide_cjk" c:identifier="g_unichar_iswide_cjk" version="2.12"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the character is wide in legacy East Asian locales</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_isxdigit" c:identifier="g_unichar_isxdigit"> + <doc xml:space="preserve">Determines if a character is a hexadecimal digit.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the character is a hexadecimal digit</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character.</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_iszerowidth" c:identifier="g_unichar_iszerowidth" version="2.14"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the character has zero width</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_to_utf8" c:identifier="g_unichar_to_utf8"> + <doc xml:space="preserve">Converts a single character to UTF-8.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">number of bytes written</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character code</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + <parameter name="outbuf" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </function> + <function name="unichar_tolower" c:identifier="g_unichar_tolower"> + <doc xml:space="preserve">Converts a character to lower case.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gunichar" c:type="gunichar"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character.</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_totitle" c:identifier="g_unichar_totitle"> + <doc xml:space="preserve">Converts a character to the titlecase.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the result of converting @c to titlecase. + If @c is not an uppercase or lowercase character, + @c is returned unchanged.</doc> + <type name="gunichar" c:type="gunichar"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_toupper" c:identifier="g_unichar_toupper"> + <doc xml:space="preserve">Converts a character to uppercase.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gunichar" c:type="gunichar"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_type" c:identifier="g_unichar_type"> + <doc xml:space="preserve">Classifies a Unicode character by type.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the type of the character.</doc> + <type name="UnicodeType" c:type="GUnicodeType"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_validate" c:identifier="g_unichar_validate"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @ch is a valid Unicode character</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="ch" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="unichar_xdigit_value" c:identifier="g_unichar_xdigit_value"> + <doc xml:space="preserve">Determines the numeric value of a character as a hexadecimal +digit.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">If @c is a hex digit (according to +g_unichar_isxdigit()), its numeric value. Otherwise, -1.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <docsection name="unicode"> + <doc xml:space="preserve">This section describes a number of functions for dealing with +Unicode characters and strings. There are analogues of the +traditional `ctype.h` character classification and case conversion +functions, UTF-8 analogues of some string utility functions, +functions to perform normalization, case conversion and collation +on UTF-8 strings and finally functions to convert between the UTF-8, +UTF-16 and UCS-4 encodings of Unicode. + +The implementations of the Unicode functions in GLib are based +on the Unicode Character Data tables, which are available from +[www.unicode.org](http://www.unicode.org/). + + * Unicode 4.0 was added in GLib 2.8 + * Unicode 4.1 was added in GLib 2.10 + * Unicode 5.0 was added in GLib 2.12 + * Unicode 5.1 was added in GLib 2.16.3 + * Unicode 6.0 was added in GLib 2.30 + * Unicode 6.1 was added in GLib 2.32 + * Unicode 6.2 was added in GLib 2.36 + * Unicode 6.3 was added in GLib 2.40 + * Unicode 7.0 was added in GLib 2.42 + * Unicode 8.0 was added in GLib 2.48 + * Unicode 9.0 was added in GLib 2.50.1 + * Unicode 10.0 was added in GLib 2.54 + * Unicode 11.10 was added in GLib 2.58 + * Unicode 12.0 was added in GLib 2.62 + * Unicode 12.1 was added in GLib 2.62 + * Unicode 13.0 was added in GLib 2.66</doc> + </docsection> + <function name="unicode_canonical_decomposition" c:identifier="g_unicode_canonical_decomposition" deprecated="1" deprecated-version="2.30"> + <doc xml:space="preserve">Computes the canonical decomposition of a Unicode character.</doc> + <doc-deprecated xml:space="preserve">Use the more flexible g_unichar_fully_decompose() + instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a newly allocated string of Unicode characters. + @result_len is set to the resulting length of the string.</doc> + <type name="gunichar" c:type="gunichar*"/> + </return-value> + <parameters> + <parameter name="ch" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character.</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + <parameter name="result_len" transfer-ownership="none"> + <doc xml:space="preserve">location to store the length of the return value.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </function> + <function name="unicode_canonical_ordering" c:identifier="g_unicode_canonical_ordering"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a UCS-4 encoded string.</doc> + <type name="gunichar" c:type="gunichar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the maximum length of @string to use.</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="unicode_script_from_iso15924" c:identifier="g_unicode_script_from_iso15924" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="UnicodeScript" c:type="GUnicodeScript"/> + </return-value> + <parameters> + <parameter name="iso15924" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode script</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + </parameters> + </function> + <function name="unicode_script_to_iso15924" c:identifier="g_unicode_script_to_iso15924" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="guint32" c:type="guint32"/> + </return-value> + <parameters> + <parameter name="script" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode script</doc> + <type name="UnicodeScript" c:type="GUnicodeScript"/> + </parameter> + </parameters> + </function> + <function name="unix_error_quark" c:identifier="g_unix_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="unix_fd_add" c:identifier="g_unix_fd_add" version="2.36" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ID (greater than 0) of the event source</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a file descriptor</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">IO conditions to watch for on @fd</doc> + <type name="IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="function" transfer-ownership="none" closure="3"> + <doc xml:space="preserve">a #GUnixFDSourceFunc</doc> + <type name="UnixFDSourceFunc" c:type="GUnixFDSourceFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="unix_fd_add_full" c:identifier="g_unix_fd_add_full" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ID (greater than 0) of the event source</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="priority" transfer-ownership="none"> + <doc xml:space="preserve">the priority of the source</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a file descriptor</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">IO conditions to watch for on @fd</doc> + <type name="IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="function" transfer-ownership="none" scope="notified" closure="4" destroy="5"> + <doc xml:space="preserve">a #GUnixFDSourceFunc</doc> + <type name="UnixFDSourceFunc" c:type="GUnixFDSourceFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">function to call when the idle is removed, or %NULL</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="unix_fd_source_new" c:identifier="g_unix_fd_source_new" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the newly created #GSource</doc> + <type name="Source" c:type="GSource*"/> + </return-value> + <parameters> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a file descriptor</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">IO conditions to watch for on @fd</doc> + <type name="IOCondition" c:type="GIOCondition"/> + </parameter> + </parameters> + </function> + <function name="unix_get_passwd_entry" c:identifier="g_unix_get_passwd_entry" version="2.64" throws="1"> + <doc xml:space="preserve">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`.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">passwd entry, or %NULL on error; free the returned + value with g_free()</doc> + <type name="gpointer" c:type="passwd*"/> + </return-value> + <parameters> + <parameter name="user_name" transfer-ownership="none"> + <doc xml:space="preserve">the username to get the passwd file entry for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="unix_open_pipe" c:identifier="g_unix_open_pipe" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if not (and errno will be set).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="fds" transfer-ownership="none"> + <doc xml:space="preserve">Array of two integers</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Bitfield of file descriptor flags, as for fcntl()</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="unix_set_fd_nonblocking" c:identifier="g_unix_set_fd_nonblocking" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">A file descriptor</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="nonblock" transfer-ownership="none"> + <doc xml:space="preserve">If %TRUE, set the descriptor to be non-blocking</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="unix_signal_add" c:identifier="g_unix_signal_add" shadowed-by="unix_signal_add_full" version="2.30" introspectable="0"> + <doc xml:space="preserve">A convenience function for g_unix_signal_source_new(), which +attaches to the default #GMainContext. You can remove the watch +using g_source_remove().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">An ID (greater than 0) for the event source</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="signum" transfer-ownership="none"> + <doc xml:space="preserve">Signal number</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="handler" transfer-ownership="none" closure="2"> + <doc xml:space="preserve">Callback</doc> + <type name="SourceFunc" c:type="GSourceFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Data for @handler</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="unix_signal_add_full" c:identifier="g_unix_signal_add_full" shadows="unix_signal_add" version="2.30"> + <doc xml:space="preserve">A convenience function for g_unix_signal_source_new(), which +attaches to the default #GMainContext. You can remove the watch +using g_source_remove().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">An ID (greater than 0) for the event source</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="priority" transfer-ownership="none"> + <doc xml:space="preserve">the priority of the signal source. Typically this will be in + the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="signum" transfer-ownership="none"> + <doc xml:space="preserve">Signal number</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="handler" transfer-ownership="none" scope="notified" closure="3" destroy="4"> + <doc xml:space="preserve">Callback</doc> + <type name="SourceFunc" c:type="GSourceFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Data for @handler</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">#GDestroyNotify for @handler</doc> + <type name="DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="unix_signal_source_new" c:identifier="g_unix_signal_source_new" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A newly created #GSource</doc> + <type name="Source" c:type="GSource*"/> + </return-value> + <parameters> + <parameter name="signum" transfer-ownership="none"> + <doc xml:space="preserve">A signal number</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="unlink" c:identifier="g_unlink" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">0 if the name was successfully deleted, -1 if an error + occurred</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">a pathname in the GLib file name encoding + (UTF-8 on Windows)</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="unsetenv" c:identifier="g_unsetenv" version="2.4"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="variable" transfer-ownership="none"> + <doc xml:space="preserve">the environment variable to remove, must + not contain '='</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="uri_build" c:identifier="g_uri_build" moved-to="Uri.build" version="2.66"> + <doc xml:space="preserve">Creates a new #GUri from the given components according to @flags. + +See also g_uri_build_with_user(), which allows specifying the +components of the "userinfo" separately.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </return-value> + <parameters> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to build the #GUri</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + <parameter name="scheme" transfer-ownership="none"> + <doc xml:space="preserve">the URI scheme</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="userinfo" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the userinfo component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="host" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the host component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="port" transfer-ownership="none"> + <doc xml:space="preserve">the port, or `-1`</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the path component</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="query" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the query component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="fragment" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the fragment, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="uri_build_with_user" c:identifier="g_uri_build_with_user" moved-to="Uri.build_with_user" version="2.66"> + <doc xml:space="preserve">Creates a new #GUri from the given components according to @flags +(%G_URI_FLAGS_HAS_PASSWORD is added unconditionally). The @flags must be +coherent with the passed values, in particular use `%`-encoded values with +%G_URI_FLAGS_ENCODED. + +In contrast to g_uri_build(), this allows specifying the components +of the ‘userinfo’ field separately. Note that @user must be non-%NULL +if either @password or @auth_params is non-%NULL.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUri</doc> + <type name="Uri" c:type="GUri*"/> + </return-value> + <parameters> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to build the #GUri</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + <parameter name="scheme" transfer-ownership="none"> + <doc xml:space="preserve">the URI scheme</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="user" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the user component of the userinfo, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="password" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the password component of the userinfo, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="auth_params" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the auth params of the userinfo, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="host" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the host component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="port" transfer-ownership="none"> + <doc xml:space="preserve">the port, or `-1`</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the path component</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="query" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the query component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="fragment" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the fragment, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="uri_error_quark" c:identifier="g_uri_error_quark" moved-to="Uri.error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="uri_escape_bytes" c:identifier="g_uri_escape_bytes" moved-to="Uri.escape_bytes" version="2.66"> + <doc xml:space="preserve">Escapes arbitrary data 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. + +Though technically incorrect, this will also allow escaping nul +bytes as `%``00`.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an escaped version of @unescaped. + The returned string should be freed when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="unescaped" transfer-ownership="none"> + <doc xml:space="preserve">the unescaped input data.</doc> + <array length="1" zero-terminated="0" c:type="const guint8*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @unescaped</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="reserved_chars_allowed" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string of reserved + characters that are allowed to be used, or %NULL.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="uri_escape_string" c:identifier="g_uri_escape_string" moved-to="Uri.escape_string" version="2.16"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an escaped version of @unescaped. The +returned string should be freed when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="unescaped" transfer-ownership="none"> + <doc xml:space="preserve">the unescaped input string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="reserved_chars_allowed" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string of reserved + characters that are allowed to be used, or %NULL.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="allow_utf8" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the result can include UTF-8 characters.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="uri_is_valid" c:identifier="g_uri_is_valid" moved-to="Uri.is_valid" version="2.66" throws="1"> + <doc xml:space="preserve">Parses @uri_string according to @flags, to determine whether it is a valid +[absolute URI][relative-absolute-uris], i.e. it does not need to be resolved +relative to another URI using g_uri_parse_relative(). + +If it’s not a valid URI, an error is returned explaining how it’s invalid. + +See g_uri_split(), and the definition of #GUriFlags, for more +information on the effect of @flags.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @uri_string is a valid absolute URI, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="uri_string" transfer-ownership="none"> + <doc xml:space="preserve">a string containing an absolute URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for parsing @uri_string</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + </parameters> + </function> + <function name="uri_join" c:identifier="g_uri_join" moved-to="Uri.join" version="2.66"> + <doc xml:space="preserve">Joins the given components together according to @flags to create +an absolute URI string. @path may not be %NULL (though it may be the empty +string). + +When @host is present, @path must either be empty or begin with a slash (`/`) +character. When @host is not present, @path cannot begin with two slash + characters (`//`). See +[RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3). + +See also g_uri_join_with_user(), which allows specifying the +components of the ‘userinfo’ separately. + +%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set +in @flags.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an absolute URI string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to build the URI string</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + <parameter name="scheme" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the URI scheme, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="userinfo" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the userinfo component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="host" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the host component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="port" transfer-ownership="none"> + <doc xml:space="preserve">the port, or `-1`</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the path component</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="query" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the query component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="fragment" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the fragment, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="uri_join_with_user" c:identifier="g_uri_join_with_user" moved-to="Uri.join_with_user" version="2.66"> + <doc xml:space="preserve">Joins the given components together according to @flags to create +an absolute URI string. @path may not be %NULL (though it may be the empty +string). + +In contrast to g_uri_join(), this allows specifying the components +of the ‘userinfo’ separately. It otherwise behaves the same. + +%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set +in @flags.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an absolute URI string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to build the URI string</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + <parameter name="scheme" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the URI scheme, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="user" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the user component of the userinfo, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="password" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the password component of the userinfo, or + %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="auth_params" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the auth params of the userinfo, or + %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="host" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the host component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="port" transfer-ownership="none"> + <doc xml:space="preserve">the port, or `-1`</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the path component</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="query" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the query component, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="fragment" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the fragment, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="uri_list_extract_uris" c:identifier="g_uri_list_extract_uris" moved-to="Uri.list_extract_uris" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated %NULL-terminated list + of strings holding the individual URIs. The array should be freed + with g_strfreev().</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="uri_list" transfer-ownership="none"> + <doc xml:space="preserve">an URI list</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="uri_parse" c:identifier="g_uri_parse" moved-to="Uri.parse" version="2.66" throws="1"> + <doc xml:space="preserve">Parses @uri_string according to @flags. If the result is not a +valid [absolute URI][relative-absolute-uris], it will be discarded, and an +error returned.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUri, or NULL on error.</doc> + <type name="Uri" c:type="GUri*"/> + </return-value> + <parameters> + <parameter name="uri_string" transfer-ownership="none"> + <doc xml:space="preserve">a string representing an absolute URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to parse @uri_string</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + </parameters> + </function> + <function name="uri_parse_params" c:identifier="g_uri_parse_params" moved-to="Uri.parse_params" version="2.66" throws="1"> + <doc xml:space="preserve">Many URI schemes include one or more attribute/value pairs as part of the URI +value. This method can be used to parse them into a hash table. When an +attribute has multiple occurrences, the last value is the final returned +value. If you need to handle repeated attributes differently, use +#GUriParamsIter. + +The @params string is assumed to still be `%`-encoded, but the returned +values will be fully decoded. (Thus it is possible that the returned values +may contain `=` or @separators, if the value was encoded in the input.) +Invalid `%`-encoding is treated as with the %G_URI_FLAGS_PARSE_RELAXED +rules for g_uri_parse(). (However, if @params is the path or query string +from a #GUri that was parsed without %G_URI_FLAGS_PARSE_RELAXED and +%G_URI_FLAGS_ENCODED, then you already know that it does not contain any +invalid encoding.) + +%G_URI_PARAMS_WWW_FORM is handled as documented for g_uri_params_iter_init(). + +If %G_URI_PARAMS_CASE_INSENSITIVE is passed to @flags, attributes will be +compared case-insensitively, so a params string `attr=123&Attr=456` will only +return a single attribute–value pair, `Attr=456`. Case will be preserved in +the returned attributes. + +If @params cannot be parsed (for example, it contains two @separators +characters in a row), then @error is set and %NULL is returned.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + A hash table of attribute/value pairs, with both names and values + fully-decoded; or %NULL on error.</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="utf8"/> + <type name="utf8"/> + </type> + </return-value> + <parameters> + <parameter name="params" transfer-ownership="none"> + <doc xml:space="preserve">a `%`-encoded string containing `attribute=value` + parameters</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @params, or `-1` if it is nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="separators" transfer-ownership="none"> + <doc xml:space="preserve">the separator byte character set between parameters. (usually + `&`, but sometimes `;` or both `&;`). 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. You may pass an empty set, in which case + no splitting will occur.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags to modify the way the parameters are handled.</doc> + <type name="UriParamsFlags" c:type="GUriParamsFlags"/> + </parameter> + </parameters> + </function> + <function name="uri_parse_scheme" c:identifier="g_uri_parse_scheme" moved-to="Uri.parse_scheme" version="2.16"> + <doc xml:space="preserve">Gets the scheme portion of a URI string. +[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme +as: +|[ +URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] +]| +Common schemes include `file`, `https`, `svn+ssh`, etc.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">The ‘scheme’ component of the URI, or + %NULL on error. The returned string should be freed when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="uri_peek_scheme" c:identifier="g_uri_peek_scheme" moved-to="Uri.peek_scheme" version="2.66"> + <doc xml:space="preserve">Gets the scheme portion of a URI string. +[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme +as: +|[ +URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] +]| +Common schemes include `file`, `https`, `svn+ssh`, etc. + +Unlike g_uri_parse_scheme(), the returned scheme is normalized to +all-lowercase and does not need to be freed.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The ‘scheme’ component of the URI, or + %NULL on error. The returned string is normalized to all-lowercase, and + interned via g_intern_string(), so it does not need to be freed.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a valid URI.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="uri_resolve_relative" c:identifier="g_uri_resolve_relative" moved-to="Uri.resolve_relative" version="2.66" throws="1"> + <doc xml:space="preserve">Parses @uri_ref according to @flags and, if it is a +[relative URI][relative-absolute-uris], resolves it relative to +@base_uri_string. If the result is not a valid absolute URI, it will be +discarded, and an error returned. + +(If @base_uri_string is %NULL, this just returns @uri_ref, or +%NULL if @uri_ref is invalid or not absolute.)</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the resolved URI string, +or NULL on error.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="base_uri_string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string representing a base URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="uri_ref" transfer-ownership="none"> + <doc xml:space="preserve">a string representing a relative or absolute URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to parse @uri_ref</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + </parameters> + </function> + <function name="uri_split" c:identifier="g_uri_split" moved-to="Uri.split" version="2.66" throws="1"> + <doc xml:space="preserve">Parses @uri_ref (which can be an +[absolute or relative URI][relative-absolute-uris]) according to @flags, and +returns the pieces. Any component that doesn't appear in @uri_ref will be +returned as %NULL (but note that all URIs always have a path component, +though it may be the empty string). + +If @flags contains %G_URI_FLAGS_ENCODED, then `%`-encoded characters in +@uri_ref will remain encoded in the output strings. (If not, +then all such characters will be decoded.) Note that decoding will +only work if the URI components are ASCII or UTF-8, so you will +need to use %G_URI_FLAGS_ENCODED if they are not. + +Note that the %G_URI_FLAGS_HAS_PASSWORD and +%G_URI_FLAGS_HAS_AUTH_PARAMS @flags are ignored by g_uri_split(), +since it always returns only the full userinfo; use +g_uri_split_with_user() if you want it split up.</doc> + <return-value transfer-ownership="none" skip="1"> + <doc xml:space="preserve">%TRUE if @uri_ref parsed successfully, %FALSE + on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="uri_ref" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a relative or absolute URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for parsing @uri_ref</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + <parameter name="scheme" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the scheme (converted to lowercase), or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="userinfo" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the userinfo, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="host" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + host, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="port" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + port, or `-1`</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="path" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + path</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="query" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + query, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="fragment" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the fragment, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </function> + <function name="uri_split_network" c:identifier="g_uri_split_network" moved-to="Uri.split_network" version="2.66" throws="1"> + <doc xml:space="preserve">Parses @uri_string (which must be an [absolute URI][relative-absolute-uris]) +according to @flags, and returns the pieces relevant to connecting to a host. +See the documentation for g_uri_split() for more details; this is +mostly a wrapper around that function with simpler arguments. +However, it will return an error if @uri_string is a relative URI, +or does not contain a hostname component.</doc> + <return-value transfer-ownership="none" skip="1"> + <doc xml:space="preserve">%TRUE if @uri_string parsed successfully, + %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="uri_string" transfer-ownership="none"> + <doc xml:space="preserve">a string containing an absolute URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for parsing @uri_string</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + <parameter name="scheme" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the scheme (converted to lowercase), or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="host" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + host, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="port" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + port, or `-1`</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </function> + <function name="uri_split_with_user" c:identifier="g_uri_split_with_user" moved-to="Uri.split_with_user" version="2.66" throws="1"> + <doc xml:space="preserve">Parses @uri_ref (which can be an +[absolute or relative URI][relative-absolute-uris]) according to @flags, and +returns the pieces. Any component that doesn't appear in @uri_ref will be +returned as %NULL (but note that all URIs always have a path component, +though it may be the empty string). + +See g_uri_split(), and the definition of #GUriFlags, for more +information on the effect of @flags. Note that @password will only +be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and +@auth_params will only be parsed out if @flags contains +%G_URI_FLAGS_HAS_AUTH_PARAMS.</doc> + <return-value transfer-ownership="none" skip="1"> + <doc xml:space="preserve">%TRUE if @uri_ref parsed successfully, %FALSE + on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="uri_ref" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a relative or absolute URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for parsing @uri_ref</doc> + <type name="UriFlags" c:type="GUriFlags"/> + </parameter> + <parameter name="scheme" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the scheme (converted to lowercase), or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="user" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the user, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="password" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the password, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="auth_params" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the auth_params, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="host" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + host, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="port" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + port, or `-1`</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="path" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + path</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="query" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains the + query, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="fragment" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">on return, contains + the fragment, or %NULL</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </function> + <function name="uri_unescape_bytes" c:identifier="g_uri_unescape_bytes" moved-to="Uri.unescape_bytes" version="2.66" throws="1"> + <doc xml:space="preserve">Unescapes a segment of an escaped string as binary data. + +Note that in contrast to g_uri_unescape_string(), this does allow +nul bytes to appear in the output. + +If any of the characters in @illegal_characters appears as an escaped +character in @escaped_string, then that is an error and %NULL will be +returned. This is useful if you want to avoid for instance having a slash +being expanded in an escaped path element, which might confuse pathname +handling.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an unescaped version of @escaped_string + or %NULL on error (if decoding failed, using %G_URI_ERROR_FAILED error + code). The returned #GBytes should be unreffed when no longer needed.</doc> + <type name="Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <parameter name="escaped_string" transfer-ownership="none"> + <doc xml:space="preserve">A URI-escaped string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length (in bytes) of @escaped_string to escape, or `-1` if it + is nul-terminated.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="illegal_characters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string of illegal characters + not to be allowed, or %NULL.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="uri_unescape_segment" c:identifier="g_uri_unescape_segment" moved-to="Uri.unescape_segment" version="2.16"> + <doc xml:space="preserve">Unescapes a segment of an escaped string. + +If any of the characters in @illegal_characters or the NUL +character appears as an escaped character in @escaped_string, then +that is an error and %NULL will be returned. This is useful if you +want to avoid for instance having a slash being expanded in an +escaped path element, which might confuse pathname handling. + +Note: `NUL` byte is not accepted in the output, in contrast to +g_uri_unescape_bytes().</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="escaped_string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A string, may be %NULL</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="escaped_string_end" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Pointer to end of @escaped_string, + may be %NULL</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="illegal_characters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">An optional string of illegal + characters not to be allowed, may be %NULL</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="uri_unescape_string" c:identifier="g_uri_unescape_string" moved-to="Uri.unescape_string" version="2.16"> + <doc xml:space="preserve">Unescapes a whole escaped string. + +If any of the characters in @illegal_characters or the NUL +character appears as an escaped character in @escaped_string, then +that is an error and %NULL will be returned. This is useful if you +want to avoid for instance having a slash being expanded in an +escaped path element, which might confuse pathname handling.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">an unescaped version of @escaped_string. +The returned string should be freed when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="escaped_string" transfer-ownership="none"> + <doc xml:space="preserve">an escaped string to be unescaped.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="illegal_characters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string of illegal characters + not to be allowed, or %NULL.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="usleep" c:identifier="g_usleep"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="microseconds" transfer-ownership="none"> + <doc xml:space="preserve">number of microseconds to pause</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + </parameters> + </function> + <function name="utf16_to_ucs4" c:identifier="g_utf16_to_ucs4" throws="1"> + <doc xml:space="preserve">Convert a string from UTF-16 to UCS-4. The result will be +nul-terminated.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="gunichar" c:type="gunichar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-16 encoded string</doc> + <type name="guint16" c:type="const gunichar2*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the maximum length (number of #gunichar2) of @str to use. + If @len < 0, then the string is nul-terminated.</doc> + <type name="glong" c:type="glong"/> + </parameter> + <parameter name="items_read" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">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.</doc> + <type name="glong" c:type="glong*"/> + </parameter> + <parameter name="items_written" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store number + of characters written, or %NULL. The value stored here does not include + the trailing 0 character.</doc> + <type name="glong" c:type="glong*"/> + </parameter> + </parameters> + </function> + <function name="utf16_to_utf8" c:identifier="g_utf16_to_utf8" throws="1"> + <doc xml:space="preserve">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 endianness. + +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 +unpaired surrogates or partial character sequences.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-16 encoded string</doc> + <type name="guint16" c:type="const gunichar2*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the maximum length (number of #gunichar2) of @str to use. + If @len < 0, then the string is nul-terminated.</doc> + <type name="glong" c:type="glong"/> + </parameter> + <parameter name="items_read" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">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.</doc> + <type name="glong" c:type="glong*"/> + </parameter> + <parameter name="items_written" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store number + of bytes written, or %NULL. The value stored here does not include the + trailing 0 byte.</doc> + <type name="glong" c:type="glong*"/> + </parameter> + </parameters> + </function> + <function name="utf8_casefold" c:identifier="g_utf8_casefold"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string, that is a + case independent form of @str.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">length of @str, in bytes, or -1 if @str is nul-terminated.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function name="utf8_collate" c:identifier="g_utf8_collate"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">< 0 if @str1 compares before @str2, + 0 if they compare equal, > 0 if @str1 compares after @str2.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="str1" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="str2" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="utf8_collate_key" c:identifier="g_utf8_collate_key"> + <doc xml:space="preserve">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].</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string. This string should + be freed with g_free() when you are done with it.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">length of @str, in bytes, or -1 if @str is nul-terminated.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function name="utf8_collate_key_for_filename" c:identifier="g_utf8_collate_key_for_filename" version="2.8"> + <doc xml:space="preserve">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].</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string. This string should + be freed with g_free() when you are done with it.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">length of @str, in bytes, or -1 if @str is nul-terminated.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function name="utf8_find_next_char" c:identifier="g_utf8_find_next_char"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a pointer to the found character or %NULL if @end is + set and is reached</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="p" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a position within a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="end" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to the byte following the end of the string, + or %NULL to indicate that the string is nul-terminated</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="utf8_find_prev_char" c:identifier="g_utf8_find_prev_char"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a pointer to the found character or %NULL.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">pointer to the beginning of a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="p" transfer-ownership="none"> + <doc xml:space="preserve">pointer to some position within @str</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="utf8_get_char" c:identifier="g_utf8_get_char"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the resulting character</doc> + <type name="gunichar" c:type="gunichar"/> + </return-value> + <parameters> + <parameter name="p" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to Unicode character encoded as UTF-8</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="utf8_get_char_validated" c:identifier="g_utf8_get_char_validated"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gunichar" c:type="gunichar"/> + </return-value> + <parameters> + <parameter name="p" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to Unicode character encoded as UTF-8</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="max_len" transfer-ownership="none"> + <doc xml:space="preserve">the maximum number of bytes to read, or -1 if @p is nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function name="utf8_make_valid" c:identifier="g_utf8_make_valid" version="2.52"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a valid UTF-8 string whose content resembles @str</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">string to coerce into UTF-8</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the maximum length of @str to use, in bytes. If @len < 0, + then the string is nul-terminated.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function-macro name="utf8_next_char" c:identifier="g_utf8_next_char" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="p"> + <doc xml:space="preserve">Pointer to the start of a valid UTF-8 character</doc> + </parameter> + </parameters> + </function-macro> + <function name="utf8_normalize" c:identifier="g_utf8_normalize"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly allocated string, that + is the normalized form of @str, or %NULL if @str + is not valid UTF-8.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">length of @str, in bytes, or -1 if @str is nul-terminated.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve">the type of normalization to perform.</doc> + <type name="NormalizeMode" c:type="GNormalizeMode"/> + </parameter> + </parameters> + </function> + <function name="utf8_offset_to_pointer" c:identifier="g_utf8_offset_to_pointer"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the resulting pointer</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="offset" transfer-ownership="none"> + <doc xml:space="preserve">a character offset within @str</doc> + <type name="glong" c:type="glong"/> + </parameter> + </parameters> + </function> + <function name="utf8_pointer_to_offset" c:identifier="g_utf8_pointer_to_offset"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the resulting character offset</doc> + <type name="glong" c:type="glong"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="pos" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a position within @str</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="utf8_prev_char" c:identifier="g_utf8_prev_char"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a pointer to the found character</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="p" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a position within a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="utf8_strchr" c:identifier="g_utf8_strchr"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">%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.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="p" transfer-ownership="none"> + <doc xml:space="preserve">a nul-terminated UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the maximum length of @p</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="utf8_strdown" c:identifier="g_utf8_strdown"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string, with all characters + converted to lowercase.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">length of @str, in bytes, or -1 if @str is nul-terminated.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function name="utf8_strlen" c:identifier="g_utf8_strlen"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the length of the string in characters</doc> + <type name="glong" c:type="glong"/> + </return-value> + <parameters> + <parameter name="p" transfer-ownership="none"> + <doc xml:space="preserve">pointer to the start of a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="max" transfer-ownership="none"> + <doc xml:space="preserve">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</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function name="utf8_strncpy" c:identifier="g_utf8_strncpy"> + <doc xml:space="preserve">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</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@dest</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="dest" transfer-ownership="none"> + <doc xml:space="preserve">buffer to fill with characters from @src</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="src" transfer-ownership="none"> + <doc xml:space="preserve">UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">character count</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="utf8_strrchr" c:identifier="g_utf8_strrchr"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">%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.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="p" transfer-ownership="none"> + <doc xml:space="preserve">a nul-terminated UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the maximum length of @p</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="c" transfer-ownership="none"> + <doc xml:space="preserve">a Unicode character</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + </parameters> + </function> + <function name="utf8_strreverse" c:identifier="g_utf8_strreverse" version="2.2"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated string which is the reverse of @str</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the maximum length of @str to use, in bytes. If @len < 0, + then the string is nul-terminated.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function name="utf8_strup" c:identifier="g_utf8_strup"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated string, with all characters + converted to uppercase.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">length of @str, in bytes, or -1 if @str is nul-terminated.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </function> + <function name="utf8_substring" c:identifier="g_utf8_substring" version="2.30"> + <doc xml:space="preserve">Copies a substring out of a UTF-8 encoded string. +The substring will contain @end_pos - @start_pos characters.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated copy of the requested + substring. Free with g_free() when no longer needed.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="start_pos" transfer-ownership="none"> + <doc xml:space="preserve">a character offset within @str</doc> + <type name="glong" c:type="glong"/> + </parameter> + <parameter name="end_pos" transfer-ownership="none"> + <doc xml:space="preserve">another character offset within @str</doc> + <type name="glong" c:type="glong"/> + </parameter> + </parameters> + </function> + <function name="utf8_to_ucs4" c:identifier="g_utf8_to_ucs4" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="gunichar" c:type="gunichar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the maximum length of @str to use, in bytes. If @len < 0, + then the string is nul-terminated.</doc> + <type name="glong" c:type="glong"/> + </parameter> + <parameter name="items_read" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">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.</doc> + <type name="glong" c:type="glong*"/> + </parameter> + <parameter name="items_written" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store number + of characters written or %NULL. The value here stored does not include + the trailing 0 character.</doc> + <type name="glong" c:type="glong*"/> + </parameter> + </parameters> + </function> + <function name="utf8_to_ucs4_fast" c:identifier="g_utf8_to_ucs4_fast"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a pointer to a newly allocated UCS-4 string. + This value must be freed with g_free().</doc> + <type name="gunichar" c:type="gunichar*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the maximum length of @str to use, in bytes. If @len < 0, + then the string is nul-terminated.</doc> + <type name="glong" c:type="glong"/> + </parameter> + <parameter name="items_written" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the + number of characters in the result, or %NULL.</doc> + <type name="glong" c:type="glong*"/> + </parameter> + </parameters> + </function> + <function name="utf8_to_utf16" c:identifier="g_utf8_to_utf16" throws="1"> + <doc xml:space="preserve">Convert a string from UTF-8 to UTF-16. A 0 character will be +added to the result after the converted text.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="guint16" c:type="gunichar2*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 encoded string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the maximum length (number of bytes) of @str to use. + If @len < 0, then the string is nul-terminated.</doc> + <type name="glong" c:type="glong"/> + </parameter> + <parameter name="items_read" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">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.</doc> + <type name="glong" c:type="glong*"/> + </parameter> + <parameter name="items_written" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store number + of #gunichar2 written, or %NULL. The value stored here does not include + the trailing 0.</doc> + <type name="glong" c:type="glong*"/> + </parameter> + </parameters> + </function> + <function name="utf8_validate" c:identifier="g_utf8_validate"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the text was valid UTF-8</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to character data</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="max_len" transfer-ownership="none"> + <doc xml:space="preserve">max bytes to validate, or -1 to go until NUL</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="end" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for end of valid data</doc> + <type name="utf8" c:type="const gchar**"/> + </parameter> + </parameters> + </function> + <function name="utf8_validate_len" c:identifier="g_utf8_validate_len" version="2.60"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the text was valid UTF-8</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to character data</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="max_len" transfer-ownership="none"> + <doc xml:space="preserve">max bytes to validate</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="end" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for end of valid data</doc> + <type name="utf8" c:type="const gchar**"/> + </parameter> + </parameters> + </function> + <docsection name="uuid"> + <doc xml:space="preserve">A UUID, or Universally unique identifier, is intended to uniquely +identify information in a distributed environment. For the +definition of UUID, see [RFC 4122](https://tools.ietf.org/html/rfc4122.html). + +The creation of UUIDs does not require a centralized authority. + +UUIDs are of relatively small size (128 bits, or 16 bytes). The +common string representation (ex: +1d6c0810-2bd6-45f3-9890-0268422a6f14) needs 37 bytes. + +The UUID specification defines 5 versions, and calling +g_uuid_string_random() will generate a unique (or rather random) +UUID of the most common version, version 4.</doc> + </docsection> + <function name="uuid_string_is_valid" c:identifier="g_uuid_string_is_valid" version="2.52"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @str is a valid UUID, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a string representing a UUID</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="uuid_string_random" c:identifier="g_uuid_string_random" version="2.52"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A string that should be freed with g_free().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + </function> + <function name="variant_get_gtype" c:identifier="g_variant_get_gtype"> + <return-value transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </return-value> + </function> + <function name="variant_is_object_path" c:identifier="g_variant_is_object_path" moved-to="Variant.is_object_path" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @string is a D-Bus object path</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a normal C nul-terminated string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="variant_is_signature" c:identifier="g_variant_is_signature" moved-to="Variant.is_signature" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @string is a D-Bus type signature</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a normal C nul-terminated string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="variant_parse" c:identifier="g_variant_parse" moved-to="Variant.parse" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a non-floating reference to a #GVariant, or %NULL</doc> + <type name="Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariantType, or %NULL</doc> + <type name="VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="text" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a GVariant in text form</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="limit" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to the end of @text, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="endptr" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a location to store the end pointer, or %NULL</doc> + <type name="utf8" c:type="const gchar**"/> + </parameter> + </parameters> + </function> + <function name="variant_parse_error_print_context" c:identifier="g_variant_parse_error_print_context" moved-to="Variant.parse_error_print_context" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the printed message</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">a #GError from the #GVariantParseError domain</doc> + <type name="Error" c:type="GError*"/> + </parameter> + <parameter name="source_str" transfer-ownership="none"> + <doc xml:space="preserve">the string that was given to the parser</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="variant_parse_error_quark" c:identifier="g_variant_parse_error_quark" moved-to="Variant.parse_error_quark"> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="variant_parser_get_error_quark" c:identifier="g_variant_parser_get_error_quark" moved-to="Variant.parser_get_error_quark" deprecated="1"> + <doc xml:space="preserve">Same as g_variant_error_quark().</doc> + <doc-deprecated xml:space="preserve">Use g_variant_parse_error_quark() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="variant_type_checked_" c:identifier="g_variant_type_checked_" moved-to="VariantType.checked_"> + <return-value transfer-ownership="none"> + <type name="VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <parameter name="arg0" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="variant_type_string_get_depth_" c:identifier="g_variant_type_string_get_depth_" moved-to="VariantType.string_get_depth_"> + <return-value transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="type_string" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="variant_type_string_is_valid" c:identifier="g_variant_type_string_is_valid" moved-to="VariantType.string_is_valid"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @type_string is exactly one valid type string + +Since 2.24</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="type_string" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to any string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="variant_type_string_scan" c:identifier="g_variant_type_string_scan" moved-to="VariantType.string_scan" version="2.24"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a valid type string was found</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to any string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="limit" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the end of @string, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="endptr" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the end pointer, or %NULL</doc> + <type name="utf8" c:type="const gchar**"/> + </parameter> + </parameters> + </function> + <function name="vasprintf" c:identifier="g_vasprintf" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes printed.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the return location for the newly-allocated string.</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a standard printf() format string, but notice + [string precision pitfalls][string-precision]</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">the list of arguments to insert in the output.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </function> + <docsection name="version"> + <doc xml:space="preserve">GLib provides version information, primarily useful in configure +checks for builds that have a configure script. Applications will +not typically use the features described here. + +The GLib headers annotate deprecated APIs in a way that produces +compiler warnings if these deprecated APIs are used. The warnings +can be turned off by defining the macro %GLIB_DISABLE_DEPRECATION_WARNINGS +before including the glib.h header. + +GLib also provides support for building applications against +defined subsets of deprecated or new GLib APIs. Define the macro +%GLIB_VERSION_MIN_REQUIRED to specify up to what version of GLib +you want to receive warnings about deprecated APIs. Define the +macro %GLIB_VERSION_MAX_ALLOWED to specify the newest version of +GLib whose API you want to use.</doc> + </docsection> + <function name="vfprintf" c:identifier="g_vfprintf" version="2.2" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes printed.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">the stream to write to.</doc> + <type name="gpointer" c:type="FILE*"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a standard printf() format string, but notice + [string precision pitfalls][string-precision]</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">the list of arguments to insert in the output.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </function> + <function name="vprintf" c:identifier="g_vprintf" version="2.2" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes printed.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a standard printf() format string, but notice + [string precision pitfalls][string-precision]</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">the list of arguments to insert in the output.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </function> + <function name="vsnprintf" c:identifier="g_vsnprintf" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes which would be produced if the buffer + was large enough.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the buffer to hold the output.</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="n" transfer-ownership="none"> + <doc xml:space="preserve">the maximum number of bytes to produce (including the + terminating nul character).</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a standard printf() format string, but notice + [string precision pitfalls][string-precision]</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">the list of arguments to insert in the output.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </function> + <function name="vsprintf" c:identifier="g_vsprintf" version="2.2" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes printed.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">the buffer to hold the output.</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a standard printf() format string, but notice + [string precision pitfalls][string-precision]</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">the list of arguments to insert in the output.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </function> + <function-macro name="warn_if_fail" c:identifier="g_warn_if_fail" version="2.16" introspectable="0"> + <doc xml:space="preserve">Logs a warning if the expression is not true.</doc> + <parameters> + <parameter name="expr"> + <doc xml:space="preserve">the expression to check</doc> + </parameter> + </parameters> + </function-macro> + <function name="warn_message" c:identifier="g_warn_message" introspectable="0"> + <doc xml:space="preserve">Internal function used to print messages from the public g_warn_if_reached() +and g_warn_if_fail() macros.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">log domain</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">file containing the warning</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="line" transfer-ownership="none"> + <doc xml:space="preserve">line number of the warning</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="func" transfer-ownership="none"> + <doc xml:space="preserve">function containing the warning</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="warnexpr" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">expression which failed</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <docsection name="warnings"> + <doc xml:space="preserve">GLib defines several warning functions and assertions which can be used to +warn of programmer errors when calling functions, and print error messages +from command line programs. + +The g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and +g_return_val_if_reached() macros are intended as pre-condition assertions, to +be used at the top of a public function to check that the function’s +arguments are acceptable. Any failure of such a pre-condition assertion is +considered a programming error on the part of the caller of the public API, +and the program is considered to be in an undefined state afterwards. They +are similar to the libc assert() function, but provide more context on +failures. + +For example: +|[<!-- language="C" --> +gboolean +g_dtls_connection_shutdown (GDtlsConnection *conn, + gboolean shutdown_read, + gboolean shutdown_write, + GCancellable *cancellable, + GError **error) +{ + // local variable declarations + + g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE); + g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE); + g_return_val_if_fail (error == NULL || *error == NULL, FALSE); + + // function body + + return return_val; +} +]| + +g_print(), g_printerr() and g_set_print_handler() are intended to be used for +output from command line applications, since they output to standard output +and standard error by default — whereas functions like g_message() and +g_log() may be redirected to special purpose message windows, files, or the +system journal.</doc> + </docsection> + <docsection name="windows"> + <doc xml:space="preserve">These functions provide some level of UNIX emulation on the +Windows platform. If your application really needs the POSIX +APIs, we suggest you try the Cygwin project.</doc> + </docsection> + </namespace> +</repository> diff --git a/rust-bindings/gir-files/GObject-2.0.gir b/rust-bindings/gir-files/GObject-2.0.gir new file mode 100644 index 0000000000..edaf7b3a93 --- /dev/null +++ b/rust-bindings/gir-files/GObject-2.0.gir @@ -0,0 +1,17159 @@ +<?xml version="1.0"?> +<!-- This file was automatically generated from C sources - DO NOT EDIT! +To affect the contents of this file, edit the original C definitions, +and/or use gtk-doc annotations. --> +<repository xmlns="http://www.gtk.org/introspection/core/1.0" xmlns:c="http://www.gtk.org/introspection/c/1.0" xmlns:glib="http://www.gtk.org/introspection/glib/1.0" version="1.2"> + <include name="GLib" version="2.0"/> + <package name="gobject-2.0"/> + <c:include name="glib-object.h"/> + <namespace name="GObject" version="2.0" shared-library="libgobject-2.0.so.0" c:identifier-prefixes="G" c:symbol-prefixes="g"> + <alias name="SignalCMarshaller" c:type="GSignalCMarshaller"> + <doc xml:space="preserve">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.</doc> + <type name="ClosureMarshal" c:type="GClosureMarshal"/> + </alias> + <alias name="SignalCVaMarshaller" c:type="GSignalCVaMarshaller"> + <doc xml:space="preserve">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.</doc> + <type name="VaClosureMarshal" c:type="GVaClosureMarshal"/> + </alias> + <alias name="Type" c:type="GType"> + <doc xml:space="preserve">A numerical value which represents the unique identifier of a registered +type.</doc> + <type name="gsize" c:type="gsize"/> + </alias> + <function-macro name="ADD_PRIVATE" c:identifier="G_ADD_PRIVATE" version="2.38" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TypeName"> + <doc xml:space="preserve">the name of the type in CamelCase</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="ADD_PRIVATE_DYNAMIC" c:identifier="G_ADD_PRIVATE_DYNAMIC" version="2.38" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TypeName"> + <doc xml:space="preserve">the name of the type in CamelCase</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="BINDING" c:identifier="G_BINDING" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <callback name="BaseFinalizeFunc" c:type="GBaseFinalizeFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="g_class" transfer-ownership="none"> + <doc xml:space="preserve">The #GTypeClass structure to finalize</doc> + <type name="TypeClass" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="BaseInitFunc" c:type="GBaseInitFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="g_class" transfer-ownership="none"> + <doc xml:space="preserve">The #GTypeClass structure to initialize</doc> + <type name="TypeClass" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <class name="Binding" c:symbol-prefix="binding" c:type="GBinding" version="2.26" parent="Object" glib:type-name="GBinding" glib:get-type="g_binding_get_type"> + <doc xml:space="preserve">#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</doc> + <method name="get_flags" c:identifier="g_binding_get_flags" version="2.26"> + <doc xml:space="preserve">Retrieves the flags passed when constructing the #GBinding.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GBindingFlags used by the #GBinding</doc> + <type name="BindingFlags" c:type="GBindingFlags"/> + </return-value> + <parameters> + <instance-parameter name="binding" transfer-ownership="none"> + <doc xml:space="preserve">a #GBinding</doc> + <type name="Binding" c:type="GBinding*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_source" c:identifier="g_binding_get_source" version="2.26" deprecated="1" deprecated-version="2.68"> + <doc xml:space="preserve">Retrieves the #GObject instance used as the source of the binding. + +A #GBinding can outlive the source #GObject as the binding does not hold a +strong reference to the source. If the source is destroyed before the +binding then this function will return %NULL. + +Use g_binding_dup_source() if the source or binding are used from different +threads as otherwise the pointer returned from this function might become +invalid if the source is finalized from another thread in the meantime.</doc> + <doc-deprecated xml:space="preserve">Use g_binding_dup_source() for a safer version of this +function.</doc-deprecated> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the source #GObject, or %NULL if the + source does not exist any more.</doc> + <type name="Object" c:type="GObject*"/> + </return-value> + <parameters> + <instance-parameter name="binding" transfer-ownership="none"> + <doc xml:space="preserve">a #GBinding</doc> + <type name="Binding" c:type="GBinding*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_source_property" c:identifier="g_binding_get_source_property" version="2.26"> + <doc xml:space="preserve">Retrieves the name of the property of #GBinding:source used as the source +of the binding.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the name of the source property</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="binding" transfer-ownership="none"> + <doc xml:space="preserve">a #GBinding</doc> + <type name="Binding" c:type="GBinding*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_target" c:identifier="g_binding_get_target" version="2.26" deprecated="1" deprecated-version="2.68"> + <doc xml:space="preserve">Retrieves the #GObject instance used as the target of the binding. + +A #GBinding can outlive the target #GObject as the binding does not hold a +strong reference to the target. If the target is destroyed before the +binding then this function will return %NULL. + +Use g_binding_dup_target() if the target or binding are used from different +threads as otherwise the pointer returned from this function might become +invalid if the target is finalized from another thread in the meantime.</doc> + <doc-deprecated xml:space="preserve">Use g_binding_dup_target() for a safer version of this +function.</doc-deprecated> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the target #GObject, or %NULL if the + target does not exist any more.</doc> + <type name="Object" c:type="GObject*"/> + </return-value> + <parameters> + <instance-parameter name="binding" transfer-ownership="none"> + <doc xml:space="preserve">a #GBinding</doc> + <type name="Binding" c:type="GBinding*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_target_property" c:identifier="g_binding_get_target_property" version="2.26"> + <doc xml:space="preserve">Retrieves the name of the property of #GBinding:target used as the target +of the binding.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the name of the target property</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="binding" transfer-ownership="none"> + <doc xml:space="preserve">a #GBinding</doc> + <type name="Binding" c:type="GBinding*"/> + </instance-parameter> + </parameters> + </method> + <method name="unbind" c:identifier="g_binding_unbind" version="2.38"> + <doc xml:space="preserve">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 the binding is still bound; if you want to hold on +to the #GBinding instance after calling g_binding_unbind(), you will need +to hold a reference to it. + +Note however that this function does not take ownership of @binding, it +only unrefs the reference that was initially created by +g_object_bind_property() and is owned by the binding.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="binding" transfer-ownership="none"> + <doc xml:space="preserve">a #GBinding</doc> + <type name="Binding" c:type="GBinding*"/> + </instance-parameter> + </parameters> + </method> + <property name="flags" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">Flags to be used to control the #GBinding</doc> + <type name="BindingFlags"/> + </property> + <property name="source" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The #GObject that should be used as the source of the binding</doc> + <type name="Object"/> + </property> + <property name="source-property" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="target" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The #GObject that should be used as the target of the binding</doc> + <type name="Object"/> + </property> + <property name="target-property" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + </class> + <bitfield name="BindingFlags" version="2.26" glib:type-name="GBindingFlags" glib:get-type="g_binding_flags_get_type" c:type="GBindingFlags"> + <doc xml:space="preserve">Flags to be passed to g_object_bind_property() or +g_object_bind_property_full(). + +This enumeration can be extended at later date.</doc> + <member name="default" value="0" c:identifier="G_BINDING_DEFAULT" glib:nick="default"> + <doc xml:space="preserve">The default binding; if the source property + changes, the target property is updated with its value.</doc> + </member> + <member name="bidirectional" value="1" c:identifier="G_BINDING_BIDIRECTIONAL" glib:nick="bidirectional"> + <doc xml:space="preserve">Bidirectional binding; if either the + property of the source or the property of the target changes, + the other is updated.</doc> + </member> + <member name="sync_create" value="2" c:identifier="G_BINDING_SYNC_CREATE" glib:nick="sync-create"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="invert_boolean" value="4" c:identifier="G_BINDING_INVERT_BOOLEAN" glib:nick="invert-boolean"> + <doc xml:space="preserve">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().</doc> + </member> + </bitfield> + <callback name="BindingTransformFunc" c:type="GBindingTransformFunc" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the transformation was successful, and %FALSE + otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="binding" transfer-ownership="none"> + <doc xml:space="preserve">a #GBinding</doc> + <type name="Binding" c:type="GBinding*"/> + </parameter> + <parameter name="from_value" transfer-ownership="none"> + <doc xml:space="preserve">the #GValue containing the value to transform</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="to_value" transfer-ownership="none"> + <doc xml:space="preserve">the #GValue in which to store the transformed value</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">data passed to the transform function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="BoxedCopyFunc" c:type="GBoxedCopyFunc"> + <doc xml:space="preserve">This function is provided by the user and should produce a copy +of the passed in boxed structure.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The newly created copy of the boxed structure.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="boxed" transfer-ownership="none"> + <doc xml:space="preserve">The boxed structure to be copied.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="BoxedFreeFunc" c:type="GBoxedFreeFunc"> + <doc xml:space="preserve">This function is provided by the user and should free the boxed +structure passed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="boxed" transfer-ownership="none"> + <doc xml:space="preserve">The boxed structure to be freed.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <function-macro name="CALLBACK" c:identifier="G_CALLBACK" introspectable="0"> + <doc xml:space="preserve">Cast a function pointer to a #GCallback.</doc> + <parameters> + <parameter name="f"> + <doc xml:space="preserve">a function pointer.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="CCLOSURE_SWAP_DATA" c:identifier="G_CCLOSURE_SWAP_DATA" introspectable="0"> + <doc xml:space="preserve">Checks whether the user data of the #GCClosure should be passed as the +first parameter to the callback. See g_cclosure_new_swap().</doc> + <parameters> + <parameter name="cclosure"> + <doc xml:space="preserve">a #GCClosure</doc> + </parameter> + </parameters> + </function-macro> + <record name="CClosure" c:type="GCClosure"> + <doc xml:space="preserve">A #GCClosure is a specialization of #GClosure for C function callbacks.</doc> + <field name="closure" writable="1"> + <doc xml:space="preserve">the #GClosure</doc> + <type name="Closure" c:type="GClosure"/> + </field> + <field name="callback" writable="1"> + <doc xml:space="preserve">the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </field> + <function name="marshal_BOOLEAN__BOXED_BOXED" c:identifier="g_cclosure_marshal_BOOLEAN__BOXED_BOXED"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">A #GClosure.</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">The length of the @param_values array.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">An array of #GValues holding the arguments + on which to invoke the callback of closure.</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The invocation hint given as the last argument to + g_closure_invoke().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_BOOLEAN__BOXED_BOXEDv" c:identifier="g_cclosure_marshal_BOOLEAN__BOXED_BOXEDv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__BOXED_BOXED().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_BOOLEAN__FLAGS" c:identifier="g_cclosure_marshal_BOOLEAN__FLAGS"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue which can store the returned #gboolean</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding instance and arg1</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_BOOLEAN__FLAGSv" c:identifier="g_cclosure_marshal_BOOLEAN__FLAGSv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__FLAGS().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_STRING__OBJECT_POINTER" c:identifier="g_cclosure_marshal_STRING__OBJECT_POINTER"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue, which can store the returned string</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">3</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding instance, arg1 and arg2</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_STRING__OBJECT_POINTERv" c:identifier="g_cclosure_marshal_STRING__OBJECT_POINTERv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_STRING__OBJECT_POINTER().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__BOOLEAN" c:identifier="g_cclosure_marshal_VOID__BOOLEAN"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #gboolean parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__BOOLEANv" c:identifier="g_cclosure_marshal_VOID__BOOLEANv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOOLEAN().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__BOXED" c:identifier="g_cclosure_marshal_VOID__BOXED"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #GBoxed* parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__BOXEDv" c:identifier="g_cclosure_marshal_VOID__BOXEDv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOXED().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__CHAR" c:identifier="g_cclosure_marshal_VOID__CHAR"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #gchar parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__CHARv" c:identifier="g_cclosure_marshal_VOID__CHARv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__CHAR().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__DOUBLE" c:identifier="g_cclosure_marshal_VOID__DOUBLE"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #gdouble parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__DOUBLEv" c:identifier="g_cclosure_marshal_VOID__DOUBLEv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__DOUBLE().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__ENUM" c:identifier="g_cclosure_marshal_VOID__ENUM"> + <doc xml:space="preserve">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..</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the enumeration parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__ENUMv" c:identifier="g_cclosure_marshal_VOID__ENUMv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ENUM().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__FLAGS" c:identifier="g_cclosure_marshal_VOID__FLAGS"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the flags parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__FLAGSv" c:identifier="g_cclosure_marshal_VOID__FLAGSv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLAGS().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__FLOAT" c:identifier="g_cclosure_marshal_VOID__FLOAT"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #gfloat parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__FLOATv" c:identifier="g_cclosure_marshal_VOID__FLOATv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLOAT().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__INT" c:identifier="g_cclosure_marshal_VOID__INT"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gint arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #gint parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__INTv" c:identifier="g_cclosure_marshal_VOID__INTv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__INT().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__LONG" c:identifier="g_cclosure_marshal_VOID__LONG"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, glong arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #glong parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__LONGv" c:identifier="g_cclosure_marshal_VOID__LONGv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__LONG().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__OBJECT" c:identifier="g_cclosure_marshal_VOID__OBJECT"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #GObject* parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__OBJECTv" c:identifier="g_cclosure_marshal_VOID__OBJECTv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__OBJECT().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__PARAM" c:identifier="g_cclosure_marshal_VOID__PARAM"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #GParamSpec* parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__PARAMv" c:identifier="g_cclosure_marshal_VOID__PARAMv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__PARAM().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__POINTER" c:identifier="g_cclosure_marshal_VOID__POINTER"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #gpointer parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__POINTERv" c:identifier="g_cclosure_marshal_VOID__POINTERv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__POINTER().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__STRING" c:identifier="g_cclosure_marshal_VOID__STRING"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #gchar* parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__STRINGv" c:identifier="g_cclosure_marshal_VOID__STRINGv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__STRING().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__UCHAR" c:identifier="g_cclosure_marshal_VOID__UCHAR"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #guchar parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__UCHARv" c:identifier="g_cclosure_marshal_VOID__UCHARv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UCHAR().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__UINT" c:identifier="g_cclosure_marshal_VOID__UINT"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guint arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #guint parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__UINT_POINTER" c:identifier="g_cclosure_marshal_VOID__UINT_POINTER"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">3</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding instance, arg1 and arg2</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__UINT_POINTERv" c:identifier="g_cclosure_marshal_VOID__UINT_POINTERv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT_POINTER().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__UINTv" c:identifier="g_cclosure_marshal_VOID__UINTv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__ULONG" c:identifier="g_cclosure_marshal_VOID__ULONG"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #gulong parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__ULONGv" c:identifier="g_cclosure_marshal_VOID__ULONGv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ULONG().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__VARIANT" c:identifier="g_cclosure_marshal_VOID__VARIANT" version="2.26"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #GVariant* parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__VARIANTv" c:identifier="g_cclosure_marshal_VOID__VARIANTv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VARIANT().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__VOID" c:identifier="g_cclosure_marshal_VOID__VOID"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">1</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding only the instance</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_VOID__VOIDv" c:identifier="g_cclosure_marshal_VOID__VOIDv" introspectable="0"> + <doc xml:space="preserve">The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VOID().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="marshal_generic" c:identifier="g_cclosure_marshal_generic" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">A #GClosure.</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_gvalue" transfer-ownership="none"> + <doc xml:space="preserve">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">The length of the @param_values array.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">An array of #GValues holding the arguments + on which to invoke the callback of closure.</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The invocation hint given as the last argument to + g_closure_invoke().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="marshal_generic_va" c:identifier="g_cclosure_marshal_generic_va" version="2.30" introspectable="0"> + <doc xml:space="preserve">A generic #GVaClosureMarshal function implemented via +[libffi](http://sourceware.org/libffi/).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is + invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args_list" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args_list.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="new" c:identifier="g_cclosure_new" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new #GCClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </return-value> + <parameters> + <parameter name="callback_func" transfer-ownership="none" nullable="1" allow-none="1" closure="1"> + <doc xml:space="preserve">the function to invoke</doc> + <type name="Callback" c:type="GCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="0"> + <doc xml:space="preserve">user data to pass to @callback_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy_data" transfer-ownership="none"> + <doc xml:space="preserve">destroy notify to be called when @user_data is no longer used</doc> + <type name="ClosureNotify" c:type="GClosureNotify"/> + </parameter> + </parameters> + </function> + <function name="new_object" c:identifier="g_cclosure_new_object" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GCClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </return-value> + <parameters> + <parameter name="callback_func" transfer-ownership="none"> + <doc xml:space="preserve">the function to invoke</doc> + <type name="Callback" c:type="GCallback"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject pointer to pass to @callback_func</doc> + <type name="Object" c:type="GObject*"/> + </parameter> + </parameters> + </function> + <function name="new_object_swap" c:identifier="g_cclosure_new_object_swap" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GCClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </return-value> + <parameters> + <parameter name="callback_func" transfer-ownership="none"> + <doc xml:space="preserve">the function to invoke</doc> + <type name="Callback" c:type="GCallback"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject pointer to pass to @callback_func</doc> + <type name="Object" c:type="GObject*"/> + </parameter> + </parameters> + </function> + <function name="new_swap" c:identifier="g_cclosure_new_swap" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new #GCClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </return-value> + <parameters> + <parameter name="callback_func" transfer-ownership="none" nullable="1" allow-none="1" closure="1"> + <doc xml:space="preserve">the function to invoke</doc> + <type name="Callback" c:type="GCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="0"> + <doc xml:space="preserve">user data to pass to @callback_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy_data" transfer-ownership="none"> + <doc xml:space="preserve">destroy notify to be called when @user_data is no longer used</doc> + <type name="ClosureNotify" c:type="GClosureNotify"/> + </parameter> + </parameters> + </function> + </record> + <function-macro name="CLOSURE_NEEDS_MARSHAL" c:identifier="G_CLOSURE_NEEDS_MARSHAL" introspectable="0"> + <doc xml:space="preserve">Check if the closure still needs a marshaller. See g_closure_set_marshal().</doc> + <parameters> + <parameter name="closure"> + <doc xml:space="preserve">a #GClosure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="CLOSURE_N_NOTIFIERS" c:identifier="G_CLOSURE_N_NOTIFIERS" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <parameters> + <parameter name="cl"> + <doc xml:space="preserve">a #GClosure</doc> + </parameter> + </parameters> + </function-macro> + <callback name="Callback" c:type="GCallback"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + <callback name="ClassFinalizeFunc" c:type="GClassFinalizeFunc"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="g_class" transfer-ownership="none"> + <doc xml:space="preserve">The #GTypeClass structure to finalize</doc> + <type name="TypeClass" c:type="gpointer"/> + </parameter> + <parameter name="class_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The @class_data member supplied via the #GTypeInfo structure</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="ClassInitFunc" c:type="GClassInitFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="g_class" transfer-ownership="none"> + <doc xml:space="preserve">The #GTypeClass structure to initialize.</doc> + <type name="TypeClass" c:type="gpointer"/> + </parameter> + <parameter name="class_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The @class_data member supplied via the #GTypeInfo structure.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="Closure" c:type="GClosure" glib:type-name="GClosure" glib:get-type="g_closure_get_type" c:symbol-prefix="closure"> + <doc xml:space="preserve">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.</doc> + <field name="ref_count" readable="0" bits="15" private="1"> + <type name="guint" c:type="volatile guint"/> + </field> + <field name="meta_marshal_nouse" readable="0" bits="1" private="1"> + <type name="guint" c:type="volatile guint"/> + </field> + <field name="n_guards" readable="0" bits="1" private="1"> + <type name="guint" c:type="volatile guint"/> + </field> + <field name="n_fnotifiers" readable="0" bits="2" private="1"> + <type name="guint" c:type="volatile guint"/> + </field> + <field name="n_inotifiers" readable="0" bits="8" private="1"> + <type name="guint" c:type="volatile guint"/> + </field> + <field name="in_inotify" readable="0" bits="1" private="1"> + <type name="guint" c:type="volatile guint"/> + </field> + <field name="floating" readable="0" bits="1" private="1"> + <type name="guint" c:type="volatile guint"/> + </field> + <field name="derivative_flag" readable="0" bits="1" private="1"> + <type name="guint" c:type="volatile guint"/> + </field> + <field name="in_marshal" writable="1" bits="1"> + <doc xml:space="preserve">Indicates whether the closure is currently being invoked with + g_closure_invoke()</doc> + <type name="guint" c:type="volatile guint"/> + </field> + <field name="is_invalid" writable="1" bits="1"> + <doc xml:space="preserve">Indicates whether the closure has been invalidated by + g_closure_invalidate()</doc> + <type name="guint" c:type="volatile guint"/> + </field> + <field name="marshal"> + <callback name="marshal"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="data" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="notifiers" readable="0" private="1"> + <type name="ClosureNotifyData" c:type="GClosureNotifyData*"/> + </field> + <constructor name="new_object" c:identifier="g_closure_new_object"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated #GClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </return-value> + <parameters> + <parameter name="sizeof_closure" transfer-ownership="none"> + <doc xml:space="preserve">the size of the structure to allocate, must be at least + `sizeof (GClosure)`</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject pointer to store in the @data field of the newly + allocated #GClosure</doc> + <type name="Object" c:type="GObject*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_simple" c:identifier="g_closure_new_simple"> + <doc xml:space="preserve">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; +} +]|</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new #GClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </return-value> + <parameters> + <parameter name="sizeof_closure" transfer-ownership="none"> + <doc xml:space="preserve">the size of the structure to allocate, must be at least + `sizeof (GClosure)`</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to store in the @data field of the newly allocated #GClosure</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </constructor> + <method name="add_finalize_notifier" c:identifier="g_closure_add_finalize_notifier" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">a #GClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </instance-parameter> + <parameter name="notify_data" transfer-ownership="none" nullable="1" allow-none="1" closure="1"> + <doc xml:space="preserve">data to pass to @notify_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify_func" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the callback function to register</doc> + <type name="ClosureNotify" c:type="GClosureNotify"/> + </parameter> + </parameters> + </method> + <method name="add_invalidate_notifier" c:identifier="g_closure_add_invalidate_notifier" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">a #GClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </instance-parameter> + <parameter name="notify_data" transfer-ownership="none" nullable="1" allow-none="1" closure="1"> + <doc xml:space="preserve">data to pass to @notify_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify_func" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the callback function to register</doc> + <type name="ClosureNotify" c:type="GClosureNotify"/> + </parameter> + </parameters> + </method> + <method name="add_marshal_guards" c:identifier="g_closure_add_marshal_guards" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">a #GClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </instance-parameter> + <parameter name="pre_marshal_data" transfer-ownership="none" nullable="1" allow-none="1" closure="1"> + <doc xml:space="preserve">data to pass + to @pre_marshal_notify</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="pre_marshal_notify" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">a function to call before the closure callback</doc> + <type name="ClosureNotify" c:type="GClosureNotify"/> + </parameter> + <parameter name="post_marshal_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">data to pass + to @post_marshal_notify</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="post_marshal_notify" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a function to call after the closure callback</doc> + <type name="ClosureNotify" c:type="GClosureNotify"/> + </parameter> + </parameters> + </method> + <method name="invalidate" c:identifier="g_closure_invalidate"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">#GClosure to invalidate</doc> + <type name="Closure" c:type="GClosure*"/> + </instance-parameter> + </parameters> + </method> + <method name="invoke" c:identifier="g_closure_invoke"> + <doc xml:space="preserve">Invokes the closure, i.e. executes the callback represented by the @closure.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">a #GClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </instance-parameter> + <parameter name="return_value" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure + doesn't return a value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_values array</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">an array of + #GValues holding the arguments on which to + invoke the callback of @closure</doc> + <array length="1" zero-terminated="0" c:type="const GValue*"> + <type name="Value" c:type="GValue"/> + </array> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a context-dependent invocation hint</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_closure_ref"> + <doc xml:space="preserve">Increments the reference count on a closure to force it staying +alive while the caller holds a pointer to it.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The @closure passed in, for convenience</doc> + <type name="Closure" c:type="GClosure*"/> + </return-value> + <parameters> + <instance-parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">#GClosure to increment the reference count on</doc> + <type name="Closure" c:type="GClosure*"/> + </instance-parameter> + </parameters> + </method> + <method name="remove_finalize_notifier" c:identifier="g_closure_remove_finalize_notifier" introspectable="0"> + <doc xml:space="preserve">Removes a finalization notifier. + +Notice that notifiers are automatically removed after they are run.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">a #GClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </instance-parameter> + <parameter name="notify_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data which was passed to g_closure_add_finalize_notifier() + when registering @notify_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify_func" transfer-ownership="none"> + <doc xml:space="preserve">the callback function to remove</doc> + <type name="ClosureNotify" c:type="GClosureNotify"/> + </parameter> + </parameters> + </method> + <method name="remove_invalidate_notifier" c:identifier="g_closure_remove_invalidate_notifier" introspectable="0"> + <doc xml:space="preserve">Removes an invalidation notifier. + +Notice that notifiers are automatically removed after they are run.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">a #GClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </instance-parameter> + <parameter name="notify_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data which was passed to g_closure_add_invalidate_notifier() + when registering @notify_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify_func" transfer-ownership="none"> + <doc xml:space="preserve">the callback function to remove</doc> + <type name="ClosureNotify" c:type="GClosureNotify"/> + </parameter> + </parameters> + </method> + <method name="set_marshal" c:identifier="g_closure_set_marshal" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">a #GClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </instance-parameter> + <parameter name="marshal" transfer-ownership="none"> + <doc xml:space="preserve">a #GClosureMarshal function</doc> + <type name="ClosureMarshal" c:type="GClosureMarshal"/> + </parameter> + </parameters> + </method> + <method name="set_meta_marshal" c:identifier="g_closure_set_meta_marshal" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">a #GClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </instance-parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1" closure="1"> + <doc xml:space="preserve">context-dependent data to pass + to @meta_marshal</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="meta_marshal" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GClosureMarshal function</doc> + <type name="ClosureMarshal" c:type="GClosureMarshal"/> + </parameter> + </parameters> + </method> + <method name="sink" c:identifier="g_closure_sink"> + <doc xml:space="preserve">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(). An 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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">#GClosure to decrement the initial reference count on, if it's + still being held</doc> + <type name="Closure" c:type="GClosure*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_closure_unref"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">#GClosure to decrement the reference count on</doc> + <type name="Closure" c:type="GClosure*"/> + </instance-parameter> + </parameters> + </method> + </record> + <callback name="ClosureMarshal" c:type="GClosureMarshal"> + <doc xml:space="preserve">The type used for marshaller functions.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_values array</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">an array of + #GValues holding the arguments on which to invoke the + callback of @closure</doc> + <array length="2" zero-terminated="0" c:type="const GValue*"> + <type name="Value" c:type="GValue"/> + </array> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the + last argument to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="ClosureNotify" c:type="GClosureNotify"> + <doc xml:space="preserve">The type used for the various notification callbacks which can be registered +on closures.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data specified when registering the notification callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure on which the notification is emitted</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + </parameters> + </callback> + <record name="ClosureNotifyData" c:type="GClosureNotifyData"> + <field name="data" writable="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="notify" writable="1"> + <type name="ClosureNotify" c:type="GClosureNotify"/> + </field> + </record> + <bitfield name="ConnectFlags" c:type="GConnectFlags"> + <doc xml:space="preserve">The connection flags are used to specify the behaviour of a signal's +connection.</doc> + <member name="after" value="1" c:identifier="G_CONNECT_AFTER"> + <doc xml:space="preserve">whether the handler should be called before or after the + default handler of the signal.</doc> + </member> + <member name="swapped" value="2" c:identifier="G_CONNECT_SWAPPED"> + <doc xml:space="preserve">whether the instance and data should be swapped when + calling the handler; see g_signal_connect_swapped() for an example.</doc> + </member> + </bitfield> + <function-macro name="DECLARE_DERIVABLE_TYPE" c:identifier="G_DECLARE_DERIVABLE_TYPE" version="2.44" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="ModuleObjName"> + <doc xml:space="preserve">The name of the new type, in camel case (like GtkWidget)</doc> + </parameter> + <parameter name="module_obj_name"> + <doc xml:space="preserve">The name of the new type in lowercase, with words + separated by '_' (like 'gtk_widget')</doc> + </parameter> + <parameter name="MODULE"> + <doc xml:space="preserve">The name of the module, in all caps (like 'GTK')</doc> + </parameter> + <parameter name="OBJ_NAME"> + <doc xml:space="preserve">The bare name of the type, in all caps (like 'WIDGET')</doc> + </parameter> + <parameter name="ParentName"> + <doc xml:space="preserve">the name of the parent type, in camel case (like GtkWidget)</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DECLARE_FINAL_TYPE" c:identifier="G_DECLARE_FINAL_TYPE" version="2.44" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="ModuleObjName"> + <doc xml:space="preserve">The name of the new type, in camel case (like GtkWidget)</doc> + </parameter> + <parameter name="module_obj_name"> + <doc xml:space="preserve">The name of the new type in lowercase, with words + separated by '_' (like 'gtk_widget')</doc> + </parameter> + <parameter name="MODULE"> + <doc xml:space="preserve">The name of the module, in all caps (like 'GTK')</doc> + </parameter> + <parameter name="OBJ_NAME"> + <doc xml:space="preserve">The bare name of the type, in all caps (like 'WIDGET')</doc> + </parameter> + <parameter name="ParentName"> + <doc xml:space="preserve">the name of the parent type, in camel case (like GtkWidget)</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DECLARE_INTERFACE" c:identifier="G_DECLARE_INTERFACE" version="2.44" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="ModuleObjName"> + <doc xml:space="preserve">The name of the new type, in camel case (like GtkWidget)</doc> + </parameter> + <parameter name="module_obj_name"> + <doc xml:space="preserve">The name of the new type in lowercase, with words + separated by '_' (like 'gtk_widget')</doc> + </parameter> + <parameter name="MODULE"> + <doc xml:space="preserve">The name of the module, in all caps (like 'GTK')</doc> + </parameter> + <parameter name="OBJ_NAME"> + <doc xml:space="preserve">The bare name of the type, in all caps (like 'WIDGET')</doc> + </parameter> + <parameter name="PrerequisiteName"> + <doc xml:space="preserve">the name of the prerequisite type, in camel case (like GtkWidget)</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_ABSTRACT_TYPE" c:identifier="G_DEFINE_ABSTRACT_TYPE" version="2.4" introspectable="0"> + <doc xml:space="preserve">A convenience macro for type implementations. +Similar to G_DEFINE_TYPE(), but defines an abstract type. +See G_DEFINE_TYPE_EXTENDED() for an example.</doc> + <parameters> + <parameter name="TN"> + <doc xml:space="preserve">The name of the new type, in Camel case.</doc> + </parameter> + <parameter name="t_n"> + <doc xml:space="preserve">The name of the new type, in lowercase, with words + separated by '_'.</doc> + </parameter> + <parameter name="T_P"> + <doc xml:space="preserve">The #GType of the parent type.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_ABSTRACT_TYPE_WITH_CODE" c:identifier="G_DEFINE_ABSTRACT_TYPE_WITH_CODE" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TN"> + <doc xml:space="preserve">The name of the new type, in Camel case.</doc> + </parameter> + <parameter name="t_n"> + <doc xml:space="preserve">The name of the new type, in lowercase, with words + separated by '_'.</doc> + </parameter> + <parameter name="T_P"> + <doc xml:space="preserve">The #GType of the parent type.</doc> + </parameter> + <parameter name="_C_"> + <doc xml:space="preserve">Custom code that gets inserted in the @type_name_get_type() function.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_ABSTRACT_TYPE_WITH_PRIVATE" c:identifier="G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE" version="2.38" introspectable="0"> + <doc xml:space="preserve">Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract type. +See G_DEFINE_TYPE_EXTENDED() for an example.</doc> + <parameters> + <parameter name="TN"> + <doc xml:space="preserve">The name of the new type, in Camel case.</doc> + </parameter> + <parameter name="t_n"> + <doc xml:space="preserve">The name of the new type, in lowercase, with words + separated by '_'.</doc> + </parameter> + <parameter name="T_P"> + <doc xml:space="preserve">The #GType of the parent type.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_BOXED_TYPE" c:identifier="G_DEFINE_BOXED_TYPE" version="2.26" introspectable="0"> + <doc xml:space="preserve">A convenience macro for boxed type implementations, which defines a +type_name_get_type() function registering the boxed type.</doc> + <parameters> + <parameter name="TypeName"> + <doc xml:space="preserve">The name of the new type, in Camel case</doc> + </parameter> + <parameter name="type_name"> + <doc xml:space="preserve">The name of the new type, in lowercase, with words + separated by '_'</doc> + </parameter> + <parameter name="copy_func"> + <doc xml:space="preserve">the #GBoxedCopyFunc for the new type</doc> + </parameter> + <parameter name="free_func"> + <doc xml:space="preserve">the #GBoxedFreeFunc for the new type</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_BOXED_TYPE_WITH_CODE" c:identifier="G_DEFINE_BOXED_TYPE_WITH_CODE" version="2.26" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TypeName"> + <doc xml:space="preserve">The name of the new type, in Camel case</doc> + </parameter> + <parameter name="type_name"> + <doc xml:space="preserve">The name of the new type, in lowercase, with words + separated by '_'</doc> + </parameter> + <parameter name="copy_func"> + <doc xml:space="preserve">the #GBoxedCopyFunc for the new type</doc> + </parameter> + <parameter name="free_func"> + <doc xml:space="preserve">the #GBoxedFreeFunc for the new type</doc> + </parameter> + <parameter name="_C_"> + <doc xml:space="preserve">Custom code that gets inserted in the *_get_type() function</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_DYNAMIC_TYPE" c:identifier="G_DEFINE_DYNAMIC_TYPE" version="2.14" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TN"> + <doc xml:space="preserve">The name of the new type, in Camel case.</doc> + </parameter> + <parameter name="t_n"> + <doc xml:space="preserve">The name of the new type, in lowercase, with words + separated by '_'.</doc> + </parameter> + <parameter name="T_P"> + <doc xml:space="preserve">The #GType of the parent type.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_DYNAMIC_TYPE_EXTENDED" c:identifier="G_DEFINE_DYNAMIC_TYPE_EXTENDED" version="2.14" introspectable="0"> + <doc xml:space="preserve">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); + } +} +]|</doc> + <parameters> + <parameter name="TypeName"> + <doc xml:space="preserve">The name of the new type, in Camel case.</doc> + </parameter> + <parameter name="type_name"> + <doc xml:space="preserve">The name of the new type, in lowercase, with words + separated by '_'.</doc> + </parameter> + <parameter name="TYPE_PARENT"> + <doc xml:space="preserve">The #GType of the parent type.</doc> + </parameter> + <parameter name="flags"> + <doc xml:space="preserve">#GTypeFlags to pass to g_type_module_register_type()</doc> + </parameter> + <parameter name="CODE"> + <doc xml:space="preserve">Custom code that gets inserted in the *_get_type() function.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_INTERFACE" c:identifier="G_DEFINE_INTERFACE" version="2.24" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TN"> + <doc xml:space="preserve">The name of the new type, in Camel case.</doc> + </parameter> + <parameter name="t_n"> + <doc xml:space="preserve">The name of the new type, in lowercase, with words separated by '_'.</doc> + </parameter> + <parameter name="T_P"> + <doc xml:space="preserve">The #GType of the prerequisite type for the interface, or 0 +(%G_TYPE_INVALID) for no prerequisite type.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_INTERFACE_WITH_CODE" c:identifier="G_DEFINE_INTERFACE_WITH_CODE" version="2.24" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <parameters> + <parameter name="TN"> + <doc xml:space="preserve">The name of the new type, in Camel case.</doc> + </parameter> + <parameter name="t_n"> + <doc xml:space="preserve">The name of the new type, in lowercase, with words separated by '_'.</doc> + </parameter> + <parameter name="T_P"> + <doc xml:space="preserve">The #GType of the prerequisite type for the interface, or 0 +(%G_TYPE_INVALID) for no prerequisite type.</doc> + </parameter> + <parameter name="_C_"> + <doc xml:space="preserve">Custom code that gets inserted in the *_get_type() function.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_POINTER_TYPE" c:identifier="G_DEFINE_POINTER_TYPE" version="2.26" introspectable="0"> + <doc xml:space="preserve">A convenience macro for pointer type implementations, which defines a +type_name_get_type() function registering the pointer type.</doc> + <parameters> + <parameter name="TypeName"> + <doc xml:space="preserve">The name of the new type, in Camel case</doc> + </parameter> + <parameter name="type_name"> + <doc xml:space="preserve">The name of the new type, in lowercase, with words + separated by '_'</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_POINTER_TYPE_WITH_CODE" c:identifier="G_DEFINE_POINTER_TYPE_WITH_CODE" version="2.26" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TypeName"> + <doc xml:space="preserve">The name of the new type, in Camel case</doc> + </parameter> + <parameter name="type_name"> + <doc xml:space="preserve">The name of the new type, in lowercase, with words + separated by '_'</doc> + </parameter> + <parameter name="_C_"> + <doc xml:space="preserve">Custom code that gets inserted in the *_get_type() function</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_TYPE" c:identifier="G_DEFINE_TYPE" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TN"> + <doc xml:space="preserve">The name of the new type, in Camel case.</doc> + </parameter> + <parameter name="t_n"> + <doc xml:space="preserve">The name of the new type, in lowercase, with words + separated by '_'.</doc> + </parameter> + <parameter name="T_P"> + <doc xml:space="preserve">The #GType of the parent type.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_TYPE_EXTENDED" c:identifier="G_DEFINE_TYPE_EXTENDED" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TN"> + <doc xml:space="preserve">The name of the new type, in Camel case.</doc> + </parameter> + <parameter name="t_n"> + <doc xml:space="preserve">The name of the new type, in lowercase, with words + separated by '_'.</doc> + </parameter> + <parameter name="T_P"> + <doc xml:space="preserve">The #GType of the parent type.</doc> + </parameter> + <parameter name="_f_"> + <doc xml:space="preserve">#GTypeFlags to pass to g_type_register_static()</doc> + </parameter> + <parameter name="_C_"> + <doc xml:space="preserve">Custom code that gets inserted in the *_get_type() function.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_TYPE_WITH_CODE" c:identifier="G_DEFINE_TYPE_WITH_CODE" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TN"> + <doc xml:space="preserve">The name of the new type, in Camel case.</doc> + </parameter> + <parameter name="t_n"> + <doc xml:space="preserve">The name of the new type in lowercase, with words separated by '_'.</doc> + </parameter> + <parameter name="T_P"> + <doc xml:space="preserve">The #GType of the parent type.</doc> + </parameter> + <parameter name="_C_"> + <doc xml:space="preserve">Custom code that gets inserted in the *_get_type() function.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="DEFINE_TYPE_WITH_PRIVATE" c:identifier="G_DEFINE_TYPE_WITH_PRIVATE" version="2.38" introspectable="0"> + <doc xml:space="preserve">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()</doc> + <parameters> + <parameter name="TN"> + <doc xml:space="preserve">The name of the new type, in Camel case.</doc> + </parameter> + <parameter name="t_n"> + <doc xml:space="preserve">The name of the new type, in lowercase, with words + separated by '_'.</doc> + </parameter> + <parameter name="T_P"> + <doc xml:space="preserve">The #GType of the parent type.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="ENUM_CLASS" c:identifier="G_ENUM_CLASS" introspectable="0"> + <doc xml:space="preserve">Casts a derived #GEnumClass structure into a #GEnumClass structure.</doc> + <parameters> + <parameter name="class"> + <doc xml:space="preserve">a valid #GEnumClass</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="ENUM_CLASS_TYPE" c:identifier="G_ENUM_CLASS_TYPE" introspectable="0"> + <doc xml:space="preserve">Get the type identifier from a given #GEnumClass structure.</doc> + <parameters> + <parameter name="class"> + <doc xml:space="preserve">a #GEnumClass</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="ENUM_CLASS_TYPE_NAME" c:identifier="G_ENUM_CLASS_TYPE_NAME" introspectable="0"> + <doc xml:space="preserve">Get the static type name from a given #GEnumClass structure.</doc> + <parameters> + <parameter name="class"> + <doc xml:space="preserve">a #GEnumClass</doc> + </parameter> + </parameters> + </function-macro> + <record name="EnumClass" c:type="GEnumClass"> + <doc xml:space="preserve">The class of an enumeration type holds information about its +possible values.</doc> + <field name="g_type_class" writable="1"> + <doc xml:space="preserve">the parent class</doc> + <type name="TypeClass" c:type="GTypeClass"/> + </field> + <field name="minimum" writable="1"> + <doc xml:space="preserve">the smallest possible value.</doc> + <type name="gint" c:type="gint"/> + </field> + <field name="maximum" writable="1"> + <doc xml:space="preserve">the largest possible value.</doc> + <type name="gint" c:type="gint"/> + </field> + <field name="n_values" writable="1"> + <doc xml:space="preserve">the number of possible values.</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="values" writable="1"> + <doc xml:space="preserve">an array of #GEnumValue structs describing the + individual values.</doc> + <type name="EnumValue" c:type="GEnumValue*"/> + </field> + </record> + <record name="EnumValue" c:type="GEnumValue"> + <doc xml:space="preserve">A structure which contains a single enum value, its name, and its +nickname.</doc> + <field name="value" writable="1"> + <doc xml:space="preserve">the enum value</doc> + <type name="gint" c:type="gint"/> + </field> + <field name="value_name" writable="1"> + <doc xml:space="preserve">the name of the value</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="value_nick" writable="1"> + <doc xml:space="preserve">the nickname of the value</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + </record> + <function-macro name="FLAGS_CLASS" c:identifier="G_FLAGS_CLASS" introspectable="0"> + <doc xml:space="preserve">Casts a derived #GFlagsClass structure into a #GFlagsClass structure.</doc> + <parameters> + <parameter name="class"> + <doc xml:space="preserve">a valid #GFlagsClass</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="FLAGS_CLASS_TYPE" c:identifier="G_FLAGS_CLASS_TYPE" introspectable="0"> + <doc xml:space="preserve">Get the type identifier from a given #GFlagsClass structure.</doc> + <parameters> + <parameter name="class"> + <doc xml:space="preserve">a #GFlagsClass</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="FLAGS_CLASS_TYPE_NAME" c:identifier="G_FLAGS_CLASS_TYPE_NAME" introspectable="0"> + <doc xml:space="preserve">Get the static type name from a given #GFlagsClass structure.</doc> + <parameters> + <parameter name="class"> + <doc xml:space="preserve">a #GFlagsClass</doc> + </parameter> + </parameters> + </function-macro> + <record name="FlagsClass" c:type="GFlagsClass"> + <doc xml:space="preserve">The class of a flags type holds information about its +possible values.</doc> + <field name="g_type_class" writable="1"> + <doc xml:space="preserve">the parent class</doc> + <type name="TypeClass" c:type="GTypeClass"/> + </field> + <field name="mask" writable="1"> + <doc xml:space="preserve">a mask covering all possible values.</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="n_values" writable="1"> + <doc xml:space="preserve">the number of possible values.</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="values" writable="1"> + <doc xml:space="preserve">an array of #GFlagsValue structs describing the + individual values.</doc> + <type name="FlagsValue" c:type="GFlagsValue*"/> + </field> + </record> + <record name="FlagsValue" c:type="GFlagsValue"> + <doc xml:space="preserve">A structure which contains a single flags value, its name, and its +nickname.</doc> + <field name="value" writable="1"> + <doc xml:space="preserve">the flags value</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="value_name" writable="1"> + <doc xml:space="preserve">the name of the value</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="value_nick" writable="1"> + <doc xml:space="preserve">the nickname of the value</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + </record> + <function-macro name="IMPLEMENT_INTERFACE" c:identifier="G_IMPLEMENT_INTERFACE" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TYPE_IFACE"> + <doc xml:space="preserve">The #GType of the interface to add</doc> + </parameter> + <parameter name="iface_init"> + <doc xml:space="preserve">The interface init function, of type #GInterfaceInitFunc</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IMPLEMENT_INTERFACE_DYNAMIC" c:identifier="G_IMPLEMENT_INTERFACE_DYNAMIC" version="2.24" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TYPE_IFACE"> + <doc xml:space="preserve">The #GType of the interface to add</doc> + </parameter> + <parameter name="iface_init"> + <doc xml:space="preserve">The interface init function</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="INITIALLY_UNOWNED" c:identifier="G_INITIALLY_UNOWNED" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="object"> + <doc xml:space="preserve">Object which is subject to casting.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="INITIALLY_UNOWNED_CLASS" c:identifier="G_INITIALLY_UNOWNED_CLASS" introspectable="0"> + <doc xml:space="preserve">Casts a derived #GInitiallyUnownedClass structure into a +#GInitiallyUnownedClass structure.</doc> + <parameters> + <parameter name="class"> + <doc xml:space="preserve">a valid #GInitiallyUnownedClass</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="INITIALLY_UNOWNED_GET_CLASS" c:identifier="G_INITIALLY_UNOWNED_GET_CLASS" introspectable="0"> + <doc xml:space="preserve">Get the class structure associated to a #GInitiallyUnowned instance.</doc> + <parameters> + <parameter name="object"> + <doc xml:space="preserve">a #GInitiallyUnowned instance.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_BINDING" c:identifier="G_IS_BINDING" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_ENUM_CLASS" c:identifier="G_IS_ENUM_CLASS" introspectable="0"> + <doc xml:space="preserve">Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM +or derived.</doc> + <parameters> + <parameter name="class"> + <doc xml:space="preserve">a #GEnumClass</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FLAGS_CLASS" c:identifier="G_IS_FLAGS_CLASS" introspectable="0"> + <doc xml:space="preserve">Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS +or derived.</doc> + <parameters> + <parameter name="class"> + <doc xml:space="preserve">a #GFlagsClass</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_INITIALLY_UNOWNED" c:identifier="G_IS_INITIALLY_UNOWNED" introspectable="0"> + <doc xml:space="preserve">Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED.</doc> + <parameters> + <parameter name="object"> + <doc xml:space="preserve">Instance to check for being a %G_TYPE_INITIALLY_UNOWNED.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_INITIALLY_UNOWNED_CLASS" c:identifier="G_IS_INITIALLY_UNOWNED_CLASS" introspectable="0"> + <doc xml:space="preserve">Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type +%G_TYPE_INITIALLY_UNOWNED or derived.</doc> + <parameters> + <parameter name="class"> + <doc xml:space="preserve">a #GInitiallyUnownedClass</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_OBJECT" c:identifier="G_IS_OBJECT" introspectable="0"> + <doc xml:space="preserve">Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.</doc> + <parameters> + <parameter name="object"> + <doc xml:space="preserve">Instance to check for being a %G_TYPE_OBJECT.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_OBJECT_CLASS" c:identifier="G_IS_OBJECT_CLASS" introspectable="0"> + <doc xml:space="preserve">Checks whether @class "is a" valid #GObjectClass structure of type +%G_TYPE_OBJECT or derived.</doc> + <parameters> + <parameter name="class"> + <doc xml:space="preserve">a #GObjectClass</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC" c:identifier="G_IS_PARAM_SPEC" introspectable="0"> + <doc xml:space="preserve">Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM +or derived.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a #GParamSpec</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_BOOLEAN" c:identifier="G_IS_PARAM_SPEC_BOOLEAN" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_BOXED" c:identifier="G_IS_PARAM_SPEC_BOXED" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_CHAR" c:identifier="G_IS_PARAM_SPEC_CHAR" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_CLASS" c:identifier="G_IS_PARAM_SPEC_CLASS" introspectable="0"> + <doc xml:space="preserve">Checks whether @pclass "is a" valid #GParamSpecClass structure of type +%G_TYPE_PARAM or derived.</doc> + <parameters> + <parameter name="pclass"> + <doc xml:space="preserve">a #GParamSpecClass</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_DOUBLE" c:identifier="G_IS_PARAM_SPEC_DOUBLE" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_ENUM" c:identifier="G_IS_PARAM_SPEC_ENUM" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_FLAGS" c:identifier="G_IS_PARAM_SPEC_FLAGS" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_FLOAT" c:identifier="G_IS_PARAM_SPEC_FLOAT" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_GTYPE" c:identifier="G_IS_PARAM_SPEC_GTYPE" version="2.10" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a #GParamSpec</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_INT" c:identifier="G_IS_PARAM_SPEC_INT" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_INT64" c:identifier="G_IS_PARAM_SPEC_INT64" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_LONG" c:identifier="G_IS_PARAM_SPEC_LONG" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_OBJECT" c:identifier="G_IS_PARAM_SPEC_OBJECT" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_OVERRIDE" c:identifier="G_IS_PARAM_SPEC_OVERRIDE" version="2.4" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a #GParamSpec</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_PARAM" c:identifier="G_IS_PARAM_SPEC_PARAM" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_POINTER" c:identifier="G_IS_PARAM_SPEC_POINTER" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_STRING" c:identifier="G_IS_PARAM_SPEC_STRING" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_UCHAR" c:identifier="G_IS_PARAM_SPEC_UCHAR" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_UINT" c:identifier="G_IS_PARAM_SPEC_UINT" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_UINT64" c:identifier="G_IS_PARAM_SPEC_UINT64" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_ULONG" c:identifier="G_IS_PARAM_SPEC_ULONG" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_UNICHAR" c:identifier="G_IS_PARAM_SPEC_UNICHAR" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_VALUE_ARRAY" c:identifier="G_IS_PARAM_SPEC_VALUE_ARRAY" introspectable="0" deprecated="1" deprecated-version="2.32"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY.</doc> + <doc-deprecated xml:space="preserve">Use #GArray instead of #GValueArray</doc-deprecated> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PARAM_SPEC_VARIANT" c:identifier="G_IS_PARAM_SPEC_VARIANT" version="2.26" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VARIANT.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a #GParamSpec</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TYPE_MODULE" c:identifier="G_IS_TYPE_MODULE" introspectable="0"> + <parameters> + <parameter name="module"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TYPE_MODULE_CLASS" c:identifier="G_IS_TYPE_MODULE_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TYPE_PLUGIN" c:identifier="G_IS_TYPE_PLUGIN" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TYPE_PLUGIN_CLASS" c:identifier="G_IS_TYPE_PLUGIN_CLASS" introspectable="0"> + <parameters> + <parameter name="vtable"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_VALUE" c:identifier="G_IS_VALUE" introspectable="0"> + <doc xml:space="preserve">Checks if @value is a valid and initialized #GValue structure.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">A #GValue structure.</doc> + </parameter> + </parameters> + </function-macro> + <class name="InitiallyUnowned" c:symbol-prefix="initially_unowned" c:type="GInitiallyUnowned" parent="Object" glib:type-name="GInitiallyUnowned" glib:get-type="g_initially_unowned_get_type" glib:type-struct="InitiallyUnownedClass"> + <doc xml:space="preserve">All the fields in the GInitiallyUnowned structure +are private to the #GInitiallyUnowned implementation and should never be +accessed directly.</doc> + <field name="g_type_instance"> + <type name="TypeInstance" c:type="GTypeInstance"/> + </field> + <field name="ref_count" readable="0" private="1"> + <type name="guint" c:type="volatile guint"/> + </field> + <field name="qdata" readable="0" private="1"> + <type name="GLib.Data" c:type="GData*"/> + </field> + </class> + <record name="InitiallyUnownedClass" c:type="GInitiallyUnownedClass" glib:is-gtype-struct-for="InitiallyUnowned"> + <doc xml:space="preserve">The class structure for the GInitiallyUnowned type.</doc> + <field name="g_type_class"> + <doc xml:space="preserve">the parent class</doc> + <type name="TypeClass" c:type="GTypeClass"/> + </field> + <field name="construct_properties" readable="0" private="1"> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </field> + <field name="constructor" introspectable="0"> + <callback name="constructor" introspectable="0"> + <return-value> + <type name="Object" c:type="GObject*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_construct_properties" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="construct_properties" transfer-ownership="none"> + <type name="ObjectConstructParam" c:type="GObjectConstructParam*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="set_property"> + <callback name="set_property"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </parameter> + <parameter name="property_id" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_property"> + <callback name="get_property"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </parameter> + <parameter name="property_id" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="dispose"> + <callback name="dispose"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="finalize"> + <callback name="finalize"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="dispatch_properties_changed"> + <callback name="dispatch_properties_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </parameter> + <parameter name="n_pspecs" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="pspecs" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec**"/> + </parameter> + </parameters> + </callback> + </field> + <field name="notify"> + <callback name="notify"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </parameter> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="constructed"> + <callback name="constructed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="flags" readable="0" private="1"> + <type name="gsize" c:type="gsize"/> + </field> + <field name="pdummy" readable="0" private="1"> + <array zero-terminated="0" fixed-size="6"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <callback name="InstanceInitFunc" c:type="GInstanceInitFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">The instance to initialize</doc> + <type name="TypeInstance" c:type="GTypeInstance*"/> + </parameter> + <parameter name="g_class" transfer-ownership="none"> + <doc xml:space="preserve">The class of the type the instance is + created for</doc> + <type name="TypeClass" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="InterfaceFinalizeFunc" c:type="GInterfaceFinalizeFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="g_iface" transfer-ownership="none"> + <doc xml:space="preserve">The interface structure to finalize</doc> + <type name="TypeInterface" c:type="gpointer"/> + </parameter> + <parameter name="iface_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The @interface_data supplied via the #GInterfaceInfo structure</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="InterfaceInfo" c:type="GInterfaceInfo"> + <doc xml:space="preserve">A structure that provides information to the type system which is +used specifically for managing interface types.</doc> + <field name="interface_init" writable="1"> + <doc xml:space="preserve">location of the interface initialization function</doc> + <type name="InterfaceInitFunc" c:type="GInterfaceInitFunc"/> + </field> + <field name="interface_finalize" writable="1"> + <doc xml:space="preserve">location of the interface finalization function</doc> + <type name="InterfaceFinalizeFunc" c:type="GInterfaceFinalizeFunc"/> + </field> + <field name="interface_data" writable="1"> + <doc xml:space="preserve">user-supplied data passed to the interface init/finalize functions</doc> + <type name="gpointer" c:type="gpointer"/> + </field> + </record> + <callback name="InterfaceInitFunc" c:type="GInterfaceInitFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="g_iface" transfer-ownership="none"> + <doc xml:space="preserve">The interface structure to initialize</doc> + <type name="TypeInterface" c:type="gpointer"/> + </parameter> + <parameter name="iface_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The @interface_data supplied via the #GInterfaceInfo structure</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <function-macro name="OBJECT" c:identifier="G_OBJECT" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="object"> + <doc xml:space="preserve">Object which is subject to casting.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="OBJECT_CLASS" c:identifier="G_OBJECT_CLASS" introspectable="0"> + <doc xml:space="preserve">Casts a derived #GObjectClass structure into a #GObjectClass structure.</doc> + <parameters> + <parameter name="class"> + <doc xml:space="preserve">a valid #GObjectClass</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="OBJECT_CLASS_NAME" c:identifier="G_OBJECT_CLASS_NAME" introspectable="0"> + <doc xml:space="preserve">Return the name of a class structure's type.</doc> + <parameters> + <parameter name="class"> + <doc xml:space="preserve">a valid #GObjectClass</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="OBJECT_CLASS_TYPE" c:identifier="G_OBJECT_CLASS_TYPE" introspectable="0"> + <doc xml:space="preserve">Get the type id of a class structure.</doc> + <parameters> + <parameter name="class"> + <doc xml:space="preserve">a valid #GObjectClass</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="OBJECT_GET_CLASS" c:identifier="G_OBJECT_GET_CLASS" introspectable="0"> + <doc xml:space="preserve">Get the class structure associated to a #GObject instance.</doc> + <parameters> + <parameter name="object"> + <doc xml:space="preserve">a #GObject instance.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="OBJECT_TYPE" c:identifier="G_OBJECT_TYPE" introspectable="0"> + <doc xml:space="preserve">Get the type id of an object.</doc> + <parameters> + <parameter name="object"> + <doc xml:space="preserve">Object to return the type id for.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="OBJECT_TYPE_NAME" c:identifier="G_OBJECT_TYPE_NAME" introspectable="0"> + <doc xml:space="preserve">Get the name of an object's type.</doc> + <parameters> + <parameter name="object"> + <doc xml:space="preserve">Object to return the type name for.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="OBJECT_WARN_INVALID_PROPERTY_ID" c:identifier="G_OBJECT_WARN_INVALID_PROPERTY_ID" introspectable="0"> + <doc xml:space="preserve">This macro should be used to emit a standard warning about unexpected +properties in set_property() and get_property() implementations.</doc> + <parameters> + <parameter name="object"> + <doc xml:space="preserve">the #GObject on which set_property() or get_property() was called</doc> + </parameter> + <parameter name="property_id"> + <doc xml:space="preserve">the numeric id of the property</doc> + </parameter> + <parameter name="pspec"> + <doc xml:space="preserve">the #GParamSpec of the property</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="OBJECT_WARN_INVALID_PSPEC" c:identifier="G_OBJECT_WARN_INVALID_PSPEC" introspectable="0"> + <parameters> + <parameter name="object"> + </parameter> + <parameter name="pname"> + </parameter> + <parameter name="property_id"> + </parameter> + <parameter name="pspec"> + </parameter> + </parameters> + </function-macro> + <class name="Object" c:symbol-prefix="object" c:type="GObject" glib:type-name="GObject" glib:get-type="g_object_get_type" glib:type-struct="ObjectClass"> + <doc xml:space="preserve">All the fields in the GObject structure are private +to the #GObject implementation and should never be accessed directly.</doc> + <constructor name="new" c:identifier="g_object_new" introspectable="0"> + <doc xml:space="preserve">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. Any +private data for the object is guaranteed to be initialized with zeros, as +per g_type_create_instance(). + +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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new instance of + @object_type</doc> + <type name="Object" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="object_type" transfer-ownership="none"> + <doc xml:space="preserve">the type id of the #GObject subtype to instantiate</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="first_property_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the first property</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the value of the first property, followed optionally by more + name/value pairs, followed by %NULL</doc> + <varargs/> + </parameter> + </parameters> + </constructor> + <constructor name="new_valist" c:identifier="g_object_new_valist" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new instance of @object_type</doc> + <type name="Object" c:type="GObject*"/> + </return-value> + <parameters> + <parameter name="object_type" transfer-ownership="none"> + <doc xml:space="preserve">the type id of the #GObject subtype to instantiate</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="first_property_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the first property</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="var_args" transfer-ownership="none"> + <doc xml:space="preserve">the value of the first property, followed optionally by more + name/value pairs, followed by %NULL</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_with_properties" c:identifier="g_object_new_with_properties" version="2.54" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new instance of +@object_type</doc> + <type name="Object" c:type="GObject*"/> + </return-value> + <parameters> + <parameter name="object_type" transfer-ownership="none"> + <doc xml:space="preserve">the object type to instantiate</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_properties" transfer-ownership="none"> + <doc xml:space="preserve">the number of properties</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="names" transfer-ownership="none"> + <doc xml:space="preserve">the names of each property to be set</doc> + <array length="1" zero-terminated="0" c:type="const char**"> + <type name="utf8" c:type="char*"/> + </array> + </parameter> + <parameter name="values" transfer-ownership="none"> + <doc xml:space="preserve">the values of each property to be set</doc> + <array length="1" zero-terminated="0" c:type="const GValue*"> + <type name="Value" c:type="GValue"/> + </array> + </parameter> + </parameters> + </constructor> + <constructor name="newv" c:identifier="g_object_newv" deprecated="1" deprecated-version="2.54"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_object_new_with_properties() instead. +deprecated. See #GParameter for more information.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new instance of +@object_type</doc> + <type name="Object" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="object_type" transfer-ownership="none"> + <doc xml:space="preserve">the type id of the #GObject subtype to instantiate</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_parameters" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @parameters array</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="parameters" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GParameter</doc> + <array length="1" zero-terminated="0" c:type="GParameter*"> + <type name="Parameter" c:type="GParameter"/> + </array> + </parameter> + </parameters> + </constructor> + <function name="compat_control" c:identifier="g_object_compat_control"> + <return-value transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="what" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="interface_find_property" c:identifier="g_object_interface_find_property" version="2.4"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GParamSpec for the property of the + interface with the name @property_name, or %NULL if no + such property exists.</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="g_iface" transfer-ownership="none"> + <doc xml:space="preserve">any interface vtable for the + interface, or the default vtable for the interface</doc> + <type name="TypeInterface" c:type="gpointer"/> + </parameter> + <parameter name="property_name" transfer-ownership="none"> + <doc xml:space="preserve">name of a property to look up.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="interface_install_property" c:identifier="g_object_interface_install_property" version="2.4"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="g_iface" transfer-ownership="none"> + <doc xml:space="preserve">any interface vtable for the + interface, or the default + vtable for the interface.</doc> + <type name="TypeInterface" c:type="gpointer"/> + </parameter> + <parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">the #GParamSpec for the new property</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </function> + <function name="interface_list_properties" c:identifier="g_object_interface_list_properties" version="2.4"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="container"> + <doc xml:space="preserve">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.</doc> + <array length="1" zero-terminated="0" c:type="GParamSpec**"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </array> + </return-value> + <parameters> + <parameter name="g_iface" transfer-ownership="none"> + <doc xml:space="preserve">any interface vtable for the + interface, or the default vtable for the interface</doc> + <type name="TypeInterface" c:type="gpointer"/> + </parameter> + <parameter name="n_properties_p" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">location to store number of properties returned.</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </function> + <virtual-method name="constructed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="dispatch_properties_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="n_pspecs" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="pspecs" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec**"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="dispose"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="finalize"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_property"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="property_id" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="notify" invoker="notify"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="set_property"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="property_id" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </virtual-method> + <method name="add_toggle_ref" c:identifier="g_object_add_toggle_ref" version="2.8" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="notify" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">a function to call when this reference is the + last reference to the object, or is no longer + the last reference.</doc> + <type name="ToggleNotify" c:type="GToggleNotify"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @notify</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="add_weak_pointer" c:identifier="g_object_add_weak_pointer" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">The object that should be weak referenced.</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="weak_pointer_location" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">The memory address + of a pointer.</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + </parameters> + </method> + <method name="bind_property" c:identifier="g_object_bind_property" version="2.26"> + <doc xml:space="preserve">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. + +Removing the binding by calling g_object_unref() on it must only be done if +the binding, @source and @target are only used from a single thread and it +is clear that both @source and @target outlive the binding. Especially it +is not safe to rely on this if the binding, @source or @target can be +finalized from different threads. Keep another reference to the binding and +use g_binding_unbind() instead to be on the safe side. + +A #GObject can have multiple bindings.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GBinding instance representing the + binding between the two #GObject instances. The binding is released + whenever the #GBinding reference count reaches zero.</doc> + <type name="Binding" c:type="GBinding*"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">the source #GObject</doc> + <type name="Object" c:type="gpointer"/> + </instance-parameter> + <parameter name="source_property" transfer-ownership="none"> + <doc xml:space="preserve">the property on @source to bind</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="target" transfer-ownership="none"> + <doc xml:space="preserve">the target #GObject</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="target_property" transfer-ownership="none"> + <doc xml:space="preserve">the property on @target to bind</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags to pass to #GBinding</doc> + <type name="BindingFlags" c:type="GBindingFlags"/> + </parameter> + </parameters> + </method> + <method name="bind_property_full" c:identifier="g_object_bind_property_full" shadowed-by="bind_property_with_closures" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GBinding instance representing the + binding between the two #GObject instances. The binding is released + whenever the #GBinding reference count reaches zero.</doc> + <type name="Binding" c:type="GBinding*"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">the source #GObject</doc> + <type name="Object" c:type="gpointer"/> + </instance-parameter> + <parameter name="source_property" transfer-ownership="none"> + <doc xml:space="preserve">the property on @source to bind</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="target" transfer-ownership="none"> + <doc xml:space="preserve">the target #GObject</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="target_property" transfer-ownership="none"> + <doc xml:space="preserve">the property on @target to bind</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags to pass to #GBinding</doc> + <type name="BindingFlags" c:type="GBindingFlags"/> + </parameter> + <parameter name="transform_to" transfer-ownership="none" nullable="1" allow-none="1" scope="notified"> + <doc xml:space="preserve">the transformation function + from the @source to the @target, or %NULL to use the default</doc> + <type name="BindingTransformFunc" c:type="GBindingTransformFunc"/> + </parameter> + <parameter name="transform_from" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="6" destroy="7"> + <doc xml:space="preserve">the transformation function + from the @target to the @source, or %NULL to use the default</doc> + <type name="BindingTransformFunc" c:type="GBindingTransformFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">custom data to be passed to the transformation functions, + or %NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a function to call when disposing the binding, to free + resources used by the transformation functions, or %NULL if not required</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="bind_property_with_closures" c:identifier="g_object_bind_property_with_closures" shadows="bind_property_full" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GBinding instance representing the + binding between the two #GObject instances. The binding is released + whenever the #GBinding reference count reaches zero.</doc> + <type name="Binding" c:type="GBinding*"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">the source #GObject</doc> + <type name="Object" c:type="gpointer"/> + </instance-parameter> + <parameter name="source_property" transfer-ownership="none"> + <doc xml:space="preserve">the property on @source to bind</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="target" transfer-ownership="none"> + <doc xml:space="preserve">the target #GObject</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="target_property" transfer-ownership="none"> + <doc xml:space="preserve">the property on @target to bind</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags to pass to #GBinding</doc> + <type name="BindingFlags" c:type="GBindingFlags"/> + </parameter> + <parameter name="transform_to" transfer-ownership="none"> + <doc xml:space="preserve">a #GClosure wrapping the transformation function + from the @source to the @target, or %NULL to use the default</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="transform_from" transfer-ownership="none"> + <doc xml:space="preserve">a #GClosure wrapping the transformation function + from the @target to the @source, or %NULL to use the default</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + </parameters> + </method> + <method name="connect" c:identifier="g_object_connect" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@object</doc> + <type name="Object" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="gpointer"/> + </instance-parameter> + <parameter name="signal_spec" transfer-ownership="none"> + <doc xml:space="preserve">the spec for the first signal</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">#GCallback for the first signal, followed by data for the + first signal, followed optionally by more signal + spec/callback/data triples, followed by %NULL</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="disconnect" c:identifier="g_object_disconnect" introspectable="0"> + <doc xml:space="preserve">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".</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="gpointer"/> + </instance-parameter> + <parameter name="signal_spec" transfer-ownership="none"> + <doc xml:space="preserve">the spec for the first signal</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">#GCallback for the first signal, followed by data for the first signal, + followed optionally by more signal spec/callback/data triples, + followed by %NULL</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="dup_data" c:identifier="g_object_dup_data" version="2.34" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">the #GObject to store user data on</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a string, naming the user data pointer</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="dup_func" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">function to dup the value</doc> + <type name="GLib.DuplicateFunc" c:type="GDuplicateFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">passed as user_data to @dup_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="dup_qdata" c:identifier="g_object_dup_qdata" version="2.34" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">the #GObject to store user data on</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="quark" transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark, naming the user data pointer</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="dup_func" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">function to dup the value</doc> + <type name="GLib.DuplicateFunc" c:type="GDuplicateFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">passed as user_data to @dup_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="force_floating" c:identifier="g_object_force_floating" version="2.10"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + </parameters> + </method> + <method name="freeze_notify" c:identifier="g_object_freeze_notify"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + </parameters> + </method> + <method name="get" c:identifier="g_object_get" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="gpointer"/> + </instance-parameter> + <parameter name="first_property_name" transfer-ownership="none"> + <doc xml:space="preserve">name of the first property to get</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">return location for the first property, followed optionally by more + name/return location pairs, followed by %NULL</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="get_data" c:identifier="g_object_get_data"> + <doc xml:space="preserve">Gets a named field from the objects table of associations (see g_object_set_data()).</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the data if found, + or %NULL if no such data exists.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">#GObject containing the associations</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">name of the key for that association</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_property" c:identifier="g_object_get_property"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="property_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the property to get</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">return location for the property value</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </method> + <method name="get_qdata" c:identifier="g_object_get_qdata"> + <doc xml:space="preserve">This function gets back user data pointers stored via +g_object_set_qdata().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The user data pointer set, or %NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">The GObject to get a stored user data pointer from</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="quark" transfer-ownership="none"> + <doc xml:space="preserve">A #GQuark, naming the user data pointer</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + </parameters> + </method> + <method name="get_valist" c:identifier="g_object_get_valist" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="first_property_name" transfer-ownership="none"> + <doc xml:space="preserve">name of the first property to get</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="var_args" transfer-ownership="none"> + <doc xml:space="preserve">return location for the first property, followed optionally by more + name/return location pairs, followed by %NULL</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </method> + <method name="getv" c:identifier="g_object_getv" version="2.54"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="n_properties" transfer-ownership="none"> + <doc xml:space="preserve">the number of properties</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="names" transfer-ownership="none"> + <doc xml:space="preserve">the names of each property to get</doc> + <array length="0" zero-terminated="0" c:type="const gchar**"> + <type name="utf8" c:type="gchar*"/> + </array> + </parameter> + <parameter name="values" transfer-ownership="none"> + <doc xml:space="preserve">the values of each property to get</doc> + <array length="0" zero-terminated="0" c:type="GValue*"> + <type name="Value" c:type="GValue"/> + </array> + </parameter> + </parameters> + </method> + <method name="is_floating" c:identifier="g_object_is_floating" version="2.10"> + <doc xml:space="preserve">Checks whether @object has a [floating][floating-ref] reference.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @object has a floating reference</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="gpointer"/> + </instance-parameter> + </parameters> + </method> + <method name="notify" c:identifier="g_object_notify"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="property_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of a property installed on the class of @object.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="notify_by_pspec" c:identifier="g_object_notify_by_pspec" version="2.26"> + <doc xml:space="preserve">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]); +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">the #GParamSpec of a property installed on the class of @object.</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_object_ref"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the same @object</doc> + <type name="Object" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="gpointer"/> + </instance-parameter> + </parameters> + </method> + <method name="ref_sink" c:identifier="g_object_ref_sink" version="2.10"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@object</doc> + <type name="Object" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="gpointer"/> + </instance-parameter> + </parameters> + </method> + <method name="remove_toggle_ref" c:identifier="g_object_remove_toggle_ref" version="2.8" introspectable="0"> + <doc xml:space="preserve">Removes a reference added with g_object_add_toggle_ref(). The +reference count of the object is decreased by one.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="notify" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">a function to call when this reference is the + last reference to the object, or is no longer + the last reference.</doc> + <type name="ToggleNotify" c:type="GToggleNotify"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @notify</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="remove_weak_pointer" c:identifier="g_object_remove_weak_pointer" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">The object that is weak referenced.</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="weak_pointer_location" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">The memory address + of a pointer.</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + </parameters> + </method> + <method name="replace_data" c:identifier="g_object_replace_data" version="2.34" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the existing value for @key was replaced + by @newval, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">the #GObject to store user data on</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a string, naming the user data pointer</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="oldval" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the old value to compare against</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="newval" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the new value</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a destroy notify for the new value</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + <parameter name="old_destroy" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1" scope="async"> + <doc xml:space="preserve">destroy notify for the existing value</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify*"/> + </parameter> + </parameters> + </method> + <method name="replace_qdata" c:identifier="g_object_replace_qdata" version="2.34" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the existing value for @quark was replaced + by @newval, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">the #GObject to store user data on</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="quark" transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark, naming the user data pointer</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="oldval" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the old value to compare against</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="newval" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the new value</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a destroy notify for the new value</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + <parameter name="old_destroy" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1" scope="async"> + <doc xml:space="preserve">destroy notify for the existing value</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify*"/> + </parameter> + </parameters> + </method> + <method name="run_dispose" c:identifier="g_object_run_dispose"> + <doc xml:space="preserve">Releases all references to other objects. This can be used to break +reference cycles. + +This function should only be called from object system implementations.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + </parameters> + </method> + <method name="set" c:identifier="g_object_set" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="gpointer"/> + </instance-parameter> + <parameter name="first_property_name" transfer-ownership="none"> + <doc xml:space="preserve">name of the first property to set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">value for the first property, followed optionally by more + name/value pairs, followed by %NULL</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="set_data" c:identifier="g_object_set_data"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">#GObject containing the associations.</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">name of the key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to associate with that key</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="set_data_full" c:identifier="g_object_set_data_full" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">#GObject containing the associations</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">name of the key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to associate with that key</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">function to call when the association is destroyed</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="set_property" c:identifier="g_object_set_property"> + <doc xml:space="preserve">Sets a property on an object.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="property_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the property to set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + </parameters> + </method> + <method name="set_qdata" c:identifier="g_object_set_qdata" introspectable="0"> + <doc xml:space="preserve">This sets an opaque, named pointer on an object. +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 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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">The GObject to set store a user data pointer</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="quark" transfer-ownership="none"> + <doc xml:space="preserve">A #GQuark, naming the user data pointer</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">An opaque user data pointer</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="set_qdata_full" c:identifier="g_object_set_qdata_full" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">The GObject to set store a user data pointer</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="quark" transfer-ownership="none"> + <doc xml:space="preserve">A #GQuark, naming the user data pointer</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">An opaque user data pointer</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">Function to invoke with @data as argument, when @data + needs to be freed</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="set_valist" c:identifier="g_object_set_valist" introspectable="0"> + <doc xml:space="preserve">Sets properties on an object.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="first_property_name" transfer-ownership="none"> + <doc xml:space="preserve">name of the first property to set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="var_args" transfer-ownership="none"> + <doc xml:space="preserve">value for the first property, followed optionally by more + name/value pairs, followed by %NULL</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </method> + <method name="setv" c:identifier="g_object_setv" version="2.54" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="n_properties" transfer-ownership="none"> + <doc xml:space="preserve">the number of properties</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="names" transfer-ownership="none"> + <doc xml:space="preserve">the names of each property to be set</doc> + <array length="0" zero-terminated="0" c:type="const gchar**"> + <type name="utf8" c:type="gchar*"/> + </array> + </parameter> + <parameter name="values" transfer-ownership="none"> + <doc xml:space="preserve">the values of each property to be set</doc> + <array length="0" zero-terminated="0" c:type="const GValue*"> + <type name="Value" c:type="GValue"/> + </array> + </parameter> + </parameters> + </method> + <method name="steal_data" c:identifier="g_object_steal_data"> + <doc xml:space="preserve">Remove a specified datum from the object's data associations, +without invoking the association's destroy handler.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the data if found, or %NULL + if no such data exists.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">#GObject containing the associations</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">name of the key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="steal_qdata" c:identifier="g_object_steal_qdata"> + <doc xml:space="preserve">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"); + // retrieve 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().</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">The user data pointer set, or %NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">The GObject to get a stored user data pointer from</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="quark" transfer-ownership="none"> + <doc xml:space="preserve">A #GQuark, naming the user data pointer</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + </parameters> + </method> + <method name="thaw_notify" c:identifier="g_object_thaw_notify"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_object_unref"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="gpointer"/> + </instance-parameter> + </parameters> + </method> + <method name="watch_closure" c:identifier="g_object_watch_closure"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">#GObject restricting lifetime of @closure</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">#GClosure to watch</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + </parameters> + </method> + <method name="weak_ref" c:identifier="g_object_weak_ref" introspectable="0"> + <doc xml:space="preserve">Adds a weak reference callback to an object. Weak references are +used for notification when an object is disposed. 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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">#GObject to reference weakly</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="notify" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">callback to invoke before the object is freed</doc> + <type name="WeakNotify" c:type="GWeakNotify"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">extra data to pass to notify</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="weak_unref" c:identifier="g_object_weak_unref" introspectable="0"> + <doc xml:space="preserve">Removes a weak reference callback to an object.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">#GObject to remove a weak reference from</doc> + <type name="Object" c:type="GObject*"/> + </instance-parameter> + <parameter name="notify" transfer-ownership="none" closure="1"> + <doc xml:space="preserve">callback to search for</doc> + <type name="WeakNotify" c:type="GWeakNotify"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to search for</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <field name="g_type_instance"> + <type name="TypeInstance" c:type="GTypeInstance"/> + </field> + <field name="ref_count" readable="0" private="1"> + <type name="guint" c:type="volatile guint"/> + </field> + <field name="qdata" readable="0" private="1"> + <type name="GLib.Data" c:type="GData*"/> + </field> + <glib:signal name="notify" when="first" no-recurse="1" detailed="1" action="1" no-hooks="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">the #GParamSpec of the property which changed.</doc> + <type name="ParamSpec"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="ObjectClass" c:type="GObjectClass" glib:is-gtype-struct-for="Object"> + <doc xml:space="preserve">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; +} +]|</doc> + <field name="g_type_class"> + <doc xml:space="preserve">the parent class</doc> + <type name="TypeClass" c:type="GTypeClass"/> + </field> + <field name="construct_properties" readable="0" private="1"> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </field> + <field name="constructor" introspectable="0"> + <callback name="constructor" introspectable="0"> + <return-value> + <type name="Object" c:type="GObject*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_construct_properties" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="construct_properties" transfer-ownership="none"> + <type name="ObjectConstructParam" c:type="GObjectConstructParam*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="set_property"> + <callback name="set_property"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </parameter> + <parameter name="property_id" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_property"> + <callback name="get_property"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </parameter> + <parameter name="property_id" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="dispose"> + <callback name="dispose"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="finalize"> + <callback name="finalize"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="dispatch_properties_changed"> + <callback name="dispatch_properties_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </parameter> + <parameter name="n_pspecs" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="pspecs" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec**"/> + </parameter> + </parameters> + </callback> + </field> + <field name="notify"> + <callback name="notify"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </parameter> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="constructed"> + <callback name="constructed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <type name="Object" c:type="GObject*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="flags" readable="0" private="1"> + <type name="gsize" c:type="gsize"/> + </field> + <field name="pdummy" readable="0" private="1"> + <array zero-terminated="0" fixed-size="6"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + <method name="find_property" c:identifier="g_object_class_find_property"> + <doc xml:space="preserve">Looks up the #GParamSpec for a property of a class.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GParamSpec for the property, or + %NULL if the class doesn't have a property of that name</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <instance-parameter name="oclass" transfer-ownership="none"> + <doc xml:space="preserve">a #GObjectClass</doc> + <type name="ObjectClass" c:type="GObjectClass*"/> + </instance-parameter> + <parameter name="property_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the property to look up</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="install_properties" c:identifier="g_object_class_install_properties" version="2.26"> + <doc xml:space="preserve">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]); + } + } +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="oclass" transfer-ownership="none"> + <doc xml:space="preserve">a #GObjectClass</doc> + <type name="ObjectClass" c:type="GObjectClass*"/> + </instance-parameter> + <parameter name="n_pspecs" transfer-ownership="none"> + <doc xml:space="preserve">the length of the #GParamSpecs array</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="pspecs" transfer-ownership="none"> + <doc xml:space="preserve">the #GParamSpecs array + defining the new properties</doc> + <array length="0" zero-terminated="0" c:type="GParamSpec**"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </array> + </parameter> + </parameters> + </method> + <method name="install_property" c:identifier="g_object_class_install_property"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="oclass" transfer-ownership="none"> + <doc xml:space="preserve">a #GObjectClass</doc> + <type name="ObjectClass" c:type="GObjectClass*"/> + </instance-parameter> + <parameter name="property_id" transfer-ownership="none"> + <doc xml:space="preserve">the id for the new property</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">the #GParamSpec for the new property</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </method> + <method name="list_properties" c:identifier="g_object_class_list_properties"> + <doc xml:space="preserve">Get an array of #GParamSpec* for all properties of a class.</doc> + <return-value transfer-ownership="container"> + <doc xml:space="preserve">an array of + #GParamSpec* which should be freed after use</doc> + <array length="0" zero-terminated="0" c:type="GParamSpec**"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </array> + </return-value> + <parameters> + <instance-parameter name="oclass" transfer-ownership="none"> + <doc xml:space="preserve">a #GObjectClass</doc> + <type name="ObjectClass" c:type="GObjectClass*"/> + </instance-parameter> + <parameter name="n_properties" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">return location for the length of the returned array</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </method> + <method name="override_property" c:identifier="g_object_class_override_property" version="2.4"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="oclass" transfer-ownership="none"> + <doc xml:space="preserve">a #GObjectClass</doc> + <type name="ObjectClass" c:type="GObjectClass*"/> + </instance-parameter> + <parameter name="property_id" transfer-ownership="none"> + <doc xml:space="preserve">the new property ID</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of a property registered in a parent class or + in an interface of this class.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + </record> + <record name="ObjectConstructParam" c:type="GObjectConstructParam"> + <doc xml:space="preserve">The GObjectConstructParam struct is an auxiliary +structure used to hand #GParamSpec/#GValue pairs to the @constructor of +a #GObjectClass.</doc> + <field name="pspec" writable="1"> + <doc xml:space="preserve">the #GParamSpec of the construct parameter</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </field> + <field name="value" writable="1"> + <doc xml:space="preserve">the value to set the parameter to</doc> + <type name="Value" c:type="GValue*"/> + </field> + </record> + <callback name="ObjectFinalizeFunc" c:type="GObjectFinalizeFunc"> + <doc xml:space="preserve">The type of the @finalize function of #GObjectClass.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">the #GObject being finalized</doc> + <type name="Object" c:type="GObject*"/> + </parameter> + </parameters> + </callback> + <callback name="ObjectGetPropertyFunc" c:type="GObjectGetPropertyFunc"> + <doc xml:space="preserve">The type of the @get_property function of #GObjectClass.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </parameter> + <parameter name="property_id" transfer-ownership="none"> + <doc xml:space="preserve">the numeric id under which the property was registered with + g_object_class_install_property().</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue to return the property value in</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">the #GParamSpec describing the property</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </callback> + <callback name="ObjectSetPropertyFunc" c:type="GObjectSetPropertyFunc"> + <doc xml:space="preserve">The type of the @set_property function of #GObjectClass.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="Object" c:type="GObject*"/> + </parameter> + <parameter name="property_id" transfer-ownership="none"> + <doc xml:space="preserve">the numeric id under which the property was registered with + g_object_class_install_property().</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the new value for the property</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">the #GParamSpec describing the property</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </callback> + <constant name="PARAM_MASK" value="255" c:type="G_PARAM_MASK"> + <doc xml:space="preserve">Mask containing the bits of #GParamSpec.flags which are reserved for GLib.</doc> + <type name="gint" c:type="gint"/> + </constant> + <function-macro name="PARAM_SPEC" c:identifier="G_PARAM_SPEC" introspectable="0"> + <doc xml:space="preserve">Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into +a #GParamSpec object.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_BOOLEAN" c:identifier="G_PARAM_SPEC_BOOLEAN" introspectable="0"> + <doc xml:space="preserve">Cast a #GParamSpec instance into a #GParamSpecBoolean.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_BOXED" c:identifier="G_PARAM_SPEC_BOXED" introspectable="0"> + <doc xml:space="preserve">Cast a #GParamSpec instance into a #GParamSpecBoxed.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_CHAR" c:identifier="G_PARAM_SPEC_CHAR" introspectable="0"> + <doc xml:space="preserve">Cast a #GParamSpec instance into a #GParamSpecChar.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_CLASS" c:identifier="G_PARAM_SPEC_CLASS" introspectable="0"> + <doc xml:space="preserve">Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure.</doc> + <parameters> + <parameter name="pclass"> + <doc xml:space="preserve">a valid #GParamSpecClass</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_DOUBLE" c:identifier="G_PARAM_SPEC_DOUBLE" introspectable="0"> + <doc xml:space="preserve">Cast a #GParamSpec instance into a #GParamSpecDouble.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_ENUM" c:identifier="G_PARAM_SPEC_ENUM" introspectable="0"> + <doc xml:space="preserve">Cast a #GParamSpec instance into a #GParamSpecEnum.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_FLAGS" c:identifier="G_PARAM_SPEC_FLAGS" introspectable="0"> + <doc xml:space="preserve">Cast a #GParamSpec instance into a #GParamSpecFlags.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_FLOAT" c:identifier="G_PARAM_SPEC_FLOAT" introspectable="0"> + <doc xml:space="preserve">Cast a #GParamSpec instance into a #GParamSpecFloat.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_GET_CLASS" c:identifier="G_PARAM_SPEC_GET_CLASS" introspectable="0"> + <doc xml:space="preserve">Retrieves the #GParamSpecClass of a #GParamSpec.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_GTYPE" c:identifier="G_PARAM_SPEC_GTYPE" version="2.10" introspectable="0"> + <doc xml:space="preserve">Casts a #GParamSpec into a #GParamSpecGType.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a #GParamSpec</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_INT" c:identifier="G_PARAM_SPEC_INT" introspectable="0"> + <doc xml:space="preserve">Cast a #GParamSpec instance into a #GParamSpecInt.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_INT64" c:identifier="G_PARAM_SPEC_INT64" introspectable="0"> + <doc xml:space="preserve">Cast a #GParamSpec instance into a #GParamSpecInt64.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_LONG" c:identifier="G_PARAM_SPEC_LONG" introspectable="0"> + <doc xml:space="preserve">Cast a #GParamSpec instance into a #GParamSpecLong.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_OBJECT" c:identifier="G_PARAM_SPEC_OBJECT" introspectable="0"> + <doc xml:space="preserve">Casts a #GParamSpec instance into a #GParamSpecObject.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_OVERRIDE" c:identifier="G_PARAM_SPEC_OVERRIDE" version="2.4" introspectable="0"> + <doc xml:space="preserve">Casts a #GParamSpec into a #GParamSpecOverride.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a #GParamSpec</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_PARAM" c:identifier="G_PARAM_SPEC_PARAM" introspectable="0"> + <doc xml:space="preserve">Casts a #GParamSpec instance into a #GParamSpecParam.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_POINTER" c:identifier="G_PARAM_SPEC_POINTER" introspectable="0"> + <doc xml:space="preserve">Casts a #GParamSpec instance into a #GParamSpecPointer.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_STRING" c:identifier="G_PARAM_SPEC_STRING" introspectable="0"> + <doc xml:space="preserve">Casts a #GParamSpec instance into a #GParamSpecString.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_TYPE" c:identifier="G_PARAM_SPEC_TYPE" introspectable="0"> + <doc xml:space="preserve">Retrieves the #GType of this @pspec.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_TYPE_NAME" c:identifier="G_PARAM_SPEC_TYPE_NAME" introspectable="0"> + <doc xml:space="preserve">Retrieves the #GType name of this @pspec.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_UCHAR" c:identifier="G_PARAM_SPEC_UCHAR" introspectable="0"> + <doc xml:space="preserve">Cast a #GParamSpec instance into a #GParamSpecUChar.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_UINT" c:identifier="G_PARAM_SPEC_UINT" introspectable="0"> + <doc xml:space="preserve">Cast a #GParamSpec instance into a #GParamSpecUInt.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_UINT64" c:identifier="G_PARAM_SPEC_UINT64" introspectable="0"> + <doc xml:space="preserve">Cast a #GParamSpec instance into a #GParamSpecUInt64.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_ULONG" c:identifier="G_PARAM_SPEC_ULONG" introspectable="0"> + <doc xml:space="preserve">Cast a #GParamSpec instance into a #GParamSpecULong.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_UNICHAR" c:identifier="G_PARAM_SPEC_UNICHAR" introspectable="0"> + <doc xml:space="preserve">Cast a #GParamSpec instance into a #GParamSpecUnichar.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_VALUE_ARRAY" c:identifier="G_PARAM_SPEC_VALUE_ARRAY" introspectable="0" deprecated="1" deprecated-version="2.32"> + <doc xml:space="preserve">Cast a #GParamSpec instance into a #GParamSpecValueArray.</doc> + <doc-deprecated xml:space="preserve">Use #GArray instead of #GValueArray</doc-deprecated> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec instance</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_VALUE_TYPE" c:identifier="G_PARAM_SPEC_VALUE_TYPE" introspectable="0"> + <doc xml:space="preserve">Retrieves the #GType to initialize a #GValue for this parameter.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PARAM_SPEC_VARIANT" c:identifier="G_PARAM_SPEC_VARIANT" version="2.26" introspectable="0"> + <doc xml:space="preserve">Casts a #GParamSpec into a #GParamSpecVariant.</doc> + <parameters> + <parameter name="pspec"> + <doc xml:space="preserve">a #GParamSpec</doc> + </parameter> + </parameters> + </function-macro> + <constant name="PARAM_STATIC_STRINGS" value="224" c:type="G_PARAM_STATIC_STRINGS"> + <doc xml:space="preserve">#GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. + +Since 2.13.0</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="PARAM_USER_SHIFT" value="8" c:type="G_PARAM_USER_SHIFT"> + <doc xml:space="preserve">Minimum shift count to be used for user defined flags, to be stored in +#GParamSpec.flags. The maximum allowed is 10.</doc> + <type name="gint" c:type="gint"/> + </constant> + <function-macro name="PRIVATE_FIELD" c:identifier="G_PRIVATE_FIELD" version="2.38" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TypeName"> + <doc xml:space="preserve">the name of the type in CamelCase</doc> + </parameter> + <parameter name="inst"> + <doc xml:space="preserve">the instance of @TypeName you wish to access</doc> + </parameter> + <parameter name="field_type"> + <doc xml:space="preserve">the type of the field in the private data structure</doc> + </parameter> + <parameter name="field_name"> + <doc xml:space="preserve">the name of the field in the private data structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PRIVATE_FIELD_P" c:identifier="G_PRIVATE_FIELD_P" version="2.38" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TypeName"> + <doc xml:space="preserve">the name of the type in CamelCase</doc> + </parameter> + <parameter name="inst"> + <doc xml:space="preserve">the instance of @TypeName you wish to access</doc> + </parameter> + <parameter name="field_name"> + <doc xml:space="preserve">the name of the field in the private data structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="PRIVATE_OFFSET" c:identifier="G_PRIVATE_OFFSET" version="2.38" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="TypeName"> + <doc xml:space="preserve">the name of the type in CamelCase</doc> + </parameter> + <parameter name="field"> + <doc xml:space="preserve">the name of the field in the private data structure</doc> + </parameter> + </parameters> + </function-macro> + <bitfield name="ParamFlags" c:type="GParamFlags"> + <doc xml:space="preserve">Through the #GParamFlags flag values, certain aspects of parameters +can be configured. See also #G_PARAM_STATIC_STRINGS.</doc> + <member name="readable" value="1" c:identifier="G_PARAM_READABLE"> + <doc xml:space="preserve">the parameter is readable</doc> + </member> + <member name="writable" value="2" c:identifier="G_PARAM_WRITABLE"> + <doc xml:space="preserve">the parameter is writable</doc> + </member> + <member name="readwrite" value="3" c:identifier="G_PARAM_READWRITE"> + <doc xml:space="preserve">alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE</doc> + </member> + <member name="construct" value="4" c:identifier="G_PARAM_CONSTRUCT"> + <doc xml:space="preserve">the parameter will be set upon object construction</doc> + </member> + <member name="construct_only" value="8" c:identifier="G_PARAM_CONSTRUCT_ONLY"> + <doc xml:space="preserve">the parameter can only be set upon object construction</doc> + </member> + <member name="lax_validation" value="16" c:identifier="G_PARAM_LAX_VALIDATION"> + <doc xml:space="preserve">upon parameter conversion (see g_param_value_convert()) + strict validation is not required</doc> + </member> + <member name="static_name" value="32" c:identifier="G_PARAM_STATIC_NAME"> + <doc xml:space="preserve">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</doc> + </member> + <member name="private" value="32" c:identifier="G_PARAM_PRIVATE"> + <doc xml:space="preserve">internal</doc> + </member> + <member name="static_nick" value="64" c:identifier="G_PARAM_STATIC_NICK"> + <doc xml:space="preserve">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</doc> + </member> + <member name="static_blurb" value="128" c:identifier="G_PARAM_STATIC_BLURB"> + <doc xml:space="preserve">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</doc> + </member> + <member name="explicit_notify" value="1073741824" c:identifier="G_PARAM_EXPLICIT_NOTIFY"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="deprecated" value="2147483648" c:identifier="G_PARAM_DEPRECATED"> + <doc xml:space="preserve">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</doc> + </member> + </bitfield> + <class name="ParamSpec" c:symbol-prefix="param_spec" c:type="GParamSpec" abstract="1" glib:type-name="GParam" glib:get-type="intern" glib:type-struct="ParamSpecClass" glib:fundamental="1" glib:ref-func="g_param_spec_ref_sink" glib:unref-func="g_param_spec_uref" glib:set-value-func="g_value_set_param" glib:get-value-func="g_value_get_param"> + <doc xml:space="preserve">#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 one or more 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.</doc> + <function name="internal" c:identifier="g_param_spec_internal" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">(transfer floating): a newly allocated + #GParamSpec instance, which is initially floating</doc> + <type name="ParamSpec" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="param_type" transfer-ownership="none"> + <doc xml:space="preserve">the #GType for the property; must be derived from #G_TYPE_PARAM</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the canonical name of the property</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">the nickname of the property</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">a short description of the property</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a combination of #GParamFlags</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="is_valid_name" c:identifier="g_param_spec_is_valid_name" version="2.66"> + <doc xml:space="preserve">Validate a property name for a #GParamSpec. This can be useful for +dynamically-generated properties which need to be validated at run-time +before actually trying to create them. + +See [canonical parameter names][canonical-parameter-names] for details of +the rules for valid names.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @name is a valid property name, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the canonical name of the property</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <virtual-method name="finalize"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="value_set_default"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="value_validate"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="values_cmp"> + <return-value transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + <parameter name="value1" transfer-ownership="none"> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="value2" transfer-ownership="none"> + <type name="Value" c:type="const GValue*"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_blurb" c:identifier="g_param_spec_get_blurb"> + <doc xml:space="preserve">Get the short description of a #GParamSpec.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the short description of @pspec.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_default_value" c:identifier="g_param_spec_get_default_value" version="2.38"> + <doc xml:space="preserve">Gets the default value of @pspec as a pointer to a #GValue. + +The #GValue will remain valid for the life of @pspec.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GValue which must not be modified</doc> + <type name="Value" c:type="const GValue*"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_name" c:identifier="g_param_spec_get_name"> + <doc xml:space="preserve">Get the name of a #GParamSpec. + +The name is always an "interned" string (as per g_intern_string()). +This allows for pointer-value comparisons.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the name of @pspec.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_name_quark" c:identifier="g_param_spec_get_name_quark" version="2.46"> + <doc xml:space="preserve">Gets the GQuark for the name.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the GQuark for @pspec->name.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_nick" c:identifier="g_param_spec_get_nick"> + <doc xml:space="preserve">Get the nickname of a #GParamSpec.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the nickname of @pspec.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_qdata" c:identifier="g_param_spec_get_qdata"> + <doc xml:space="preserve">Gets back user data pointers stored via g_param_spec_set_qdata().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the user data pointer set, or %NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + <parameter name="quark" transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark, naming the user data pointer</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + </parameters> + </method> + <method name="get_redirect_target" c:identifier="g_param_spec_get_redirect_target" version="2.4"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">paramspec to which requests on this + paramspec should be redirected, or %NULL if none.</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_param_spec_ref" introspectable="0"> + <doc xml:space="preserve">Increments the reference count of @pspec.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the #GParamSpec that was passed into this function</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + </parameters> + </method> + <method name="ref_sink" c:identifier="g_param_spec_ref_sink" version="2.10" introspectable="0"> + <doc xml:space="preserve">Convenience function to ref and sink a #GParamSpec.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the #GParamSpec that was passed into this function</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_qdata" c:identifier="g_param_spec_set_qdata"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">the #GParamSpec to set store a user data pointer</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + <parameter name="quark" transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark, naming the user data pointer</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an opaque user data pointer</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="set_qdata_full" c:identifier="g_param_spec_set_qdata_full" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">the #GParamSpec to set store a user data pointer</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + <parameter name="quark" transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark, naming the user data pointer</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an opaque user data pointer</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">function to invoke with @data as argument, when @data needs to + be freed</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="sink" c:identifier="g_param_spec_sink"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + </parameters> + </method> + <method name="steal_qdata" c:identifier="g_param_spec_steal_qdata"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the user data pointer set, or %NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">the #GParamSpec to get a stored user data pointer from</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + <parameter name="quark" transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark, naming the user data pointer</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_param_spec_unref" introspectable="0"> + <doc xml:space="preserve">Decrements the reference count of a @pspec.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </instance-parameter> + </parameters> + </method> + <field name="g_type_instance"> + <doc xml:space="preserve">private #GTypeInstance portion</doc> + <type name="TypeInstance" c:type="GTypeInstance"/> + </field> + <field name="name"> + <doc xml:space="preserve">name of this parameter: always an interned string</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="flags"> + <doc xml:space="preserve">#GParamFlags flags for this parameter</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </field> + <field name="value_type"> + <doc xml:space="preserve">the #GValue type for this parameter</doc> + <type name="GType" c:type="GType"/> + </field> + <field name="owner_type"> + <doc xml:space="preserve">#GType type that uses (introduces) this parameter</doc> + <type name="GType" c:type="GType"/> + </field> + <field name="_nick" readable="0" private="1"> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="_blurb" readable="0" private="1"> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="qdata" readable="0" private="1"> + <type name="GLib.Data" c:type="GData*"/> + </field> + <field name="ref_count" readable="0" private="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="param_id" readable="0" private="1"> + <type name="guint" c:type="guint"/> + </field> + </class> + <class name="ParamSpecBoolean" c:symbol-prefix="param_spec_boolean" c:type="GParamSpecBoolean" parent="ParamSpec" glib:type-name="GParamBoolean" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for boolean properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="default_value"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gboolean" c:type="gboolean"/> + </field> + </class> + <class name="ParamSpecBoxed" c:symbol-prefix="param_spec_boxed" c:type="GParamSpecBoxed" parent="ParamSpec" glib:type-name="GParamBoxed" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for boxed properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + </class> + <class name="ParamSpecChar" c:symbol-prefix="param_spec_char" c:type="GParamSpecChar" parent="ParamSpec" glib:type-name="GParamChar" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for character properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="minimum"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="gint8" c:type="gint8"/> + </field> + <field name="maximum"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="gint8" c:type="gint8"/> + </field> + <field name="default_value"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gint8" c:type="gint8"/> + </field> + </class> + <record name="ParamSpecClass" c:type="GParamSpecClass" glib:is-gtype-struct-for="ParamSpec"> + <doc xml:space="preserve">The class structure for the GParamSpec type. +Normally, GParamSpec classes are filled by +g_param_type_register_static().</doc> + <field name="g_type_class"> + <doc xml:space="preserve">the parent class</doc> + <type name="TypeClass" c:type="GTypeClass"/> + </field> + <field name="value_type"> + <doc xml:space="preserve">the #GValue type for this parameter</doc> + <type name="GType" c:type="GType"/> + </field> + <field name="finalize"> + <callback name="finalize"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="value_set_default"> + <callback name="value_set_default"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="value_validate"> + <callback name="value_validate"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="values_cmp"> + <callback name="values_cmp"> + <return-value transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + <parameter name="value1" transfer-ownership="none"> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="value2" transfer-ownership="none"> + <type name="Value" c:type="const GValue*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="dummy" readable="0" private="1"> + <array zero-terminated="0" fixed-size="4"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <class name="ParamSpecDouble" c:symbol-prefix="param_spec_double" c:type="GParamSpecDouble" parent="ParamSpec" glib:type-name="GParamDouble" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for double properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="minimum"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="gdouble" c:type="gdouble"/> + </field> + <field name="maximum"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="gdouble" c:type="gdouble"/> + </field> + <field name="default_value"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gdouble" c:type="gdouble"/> + </field> + <field name="epsilon"> + <doc xml:space="preserve">values closer than @epsilon will be considered identical + by g_param_values_cmp(); the default value is 1e-90.</doc> + <type name="gdouble" c:type="gdouble"/> + </field> + </class> + <class name="ParamSpecEnum" c:symbol-prefix="param_spec_enum" c:type="GParamSpecEnum" parent="ParamSpec" glib:type-name="GParamEnum" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for enum +properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="enum_class"> + <doc xml:space="preserve">the #GEnumClass for the enum</doc> + <type name="EnumClass" c:type="GEnumClass*"/> + </field> + <field name="default_value"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gint" c:type="gint"/> + </field> + </class> + <class name="ParamSpecFlags" c:symbol-prefix="param_spec_flags" c:type="GParamSpecFlags" parent="ParamSpec" glib:type-name="GParamFlags" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for flags +properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="flags_class"> + <doc xml:space="preserve">the #GFlagsClass for the flags</doc> + <type name="FlagsClass" c:type="GFlagsClass*"/> + </field> + <field name="default_value"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="guint" c:type="guint"/> + </field> + </class> + <class name="ParamSpecFloat" c:symbol-prefix="param_spec_float" c:type="GParamSpecFloat" parent="ParamSpec" glib:type-name="GParamFloat" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for float properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="minimum"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="gfloat" c:type="gfloat"/> + </field> + <field name="maximum"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="gfloat" c:type="gfloat"/> + </field> + <field name="default_value"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gfloat" c:type="gfloat"/> + </field> + <field name="epsilon"> + <doc xml:space="preserve">values closer than @epsilon will be considered identical + by g_param_values_cmp(); the default value is 1e-30.</doc> + <type name="gfloat" c:type="gfloat"/> + </field> + </class> + <class name="ParamSpecGType" c:symbol-prefix="param_spec_gtype" c:type="GParamSpecGType" version="2.10" parent="ParamSpec" glib:type-name="GParamGType" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for #GType properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="is_a_type"> + <doc xml:space="preserve">a #GType whose subtypes can occur as values</doc> + <type name="GType" c:type="GType"/> + </field> + </class> + <class name="ParamSpecInt" c:symbol-prefix="param_spec_int" c:type="GParamSpecInt" parent="ParamSpec" glib:type-name="GParamInt" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for integer properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="minimum"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="gint" c:type="gint"/> + </field> + <field name="maximum"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="gint" c:type="gint"/> + </field> + <field name="default_value"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gint" c:type="gint"/> + </field> + </class> + <class name="ParamSpecInt64" c:symbol-prefix="param_spec_int64" c:type="GParamSpecInt64" parent="ParamSpec" glib:type-name="GParamInt64" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for 64bit integer properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="minimum"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="gint64" c:type="gint64"/> + </field> + <field name="maximum"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="gint64" c:type="gint64"/> + </field> + <field name="default_value"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gint64" c:type="gint64"/> + </field> + </class> + <class name="ParamSpecLong" c:symbol-prefix="param_spec_long" c:type="GParamSpecLong" parent="ParamSpec" glib:type-name="GParamLong" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for long integer properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="minimum"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="glong" c:type="glong"/> + </field> + <field name="maximum"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="glong" c:type="glong"/> + </field> + <field name="default_value"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="glong" c:type="glong"/> + </field> + </class> + <class name="ParamSpecObject" c:symbol-prefix="param_spec_object" c:type="GParamSpecObject" parent="ParamSpec" glib:type-name="GParamObject" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for object properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + </class> + <class name="ParamSpecOverride" c:symbol-prefix="param_spec_override" c:type="GParamSpecOverride" version="2.4" parent="ParamSpec" glib:type-name="GParamOverride" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">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 overridden +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.</doc> + <field name="parent_instance" readable="0" private="1"> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="overridden" readable="0" private="1"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </field> + </class> + <class name="ParamSpecParam" c:symbol-prefix="param_spec_param" c:type="GParamSpecParam" parent="ParamSpec" glib:type-name="GParamParam" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM +properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + </class> + <class name="ParamSpecPointer" c:symbol-prefix="param_spec_pointer" c:type="GParamSpecPointer" parent="ParamSpec" glib:type-name="GParamPointer" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for pointer properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + </class> + <record name="ParamSpecPool" c:type="GParamSpecPool" disguised="1"> + <doc xml:space="preserve">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.</doc> + <method name="insert" c:identifier="g_param_spec_pool_insert"> + <doc xml:space="preserve">Inserts a #GParamSpec in the pool.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="pool" transfer-ownership="none"> + <doc xml:space="preserve">a #GParamSpecPool.</doc> + <type name="ParamSpecPool" c:type="GParamSpecPool*"/> + </instance-parameter> + <parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">the #GParamSpec to insert</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + <parameter name="owner_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType identifying the owner of @pspec</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </method> + <method name="list" c:identifier="g_param_spec_pool_list"> + <doc xml:space="preserve">Gets an array of all #GParamSpecs owned by @owner_type in +the pool.</doc> + <return-value transfer-ownership="container"> + <doc xml:space="preserve">a newly + allocated array containing pointers to all #GParamSpecs + owned by @owner_type in the pool</doc> + <array length="1" zero-terminated="0" c:type="GParamSpec**"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </array> + </return-value> + <parameters> + <instance-parameter name="pool" transfer-ownership="none"> + <doc xml:space="preserve">a #GParamSpecPool</doc> + <type name="ParamSpecPool" c:type="GParamSpecPool*"/> + </instance-parameter> + <parameter name="owner_type" transfer-ownership="none"> + <doc xml:space="preserve">the owner to look for</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_pspecs_p" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">return location for the length of the returned array</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </method> + <method name="list_owned" c:identifier="g_param_spec_pool_list_owned"> + <doc xml:space="preserve">Gets an #GList of all #GParamSpecs owned by @owner_type in +the pool.</doc> + <return-value transfer-ownership="container"> + <doc xml:space="preserve">a + #GList of all #GParamSpecs owned by @owner_type in + the pool#GParamSpecs.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="ParamSpec"/> + </type> + </return-value> + <parameters> + <instance-parameter name="pool" transfer-ownership="none"> + <doc xml:space="preserve">a #GParamSpecPool</doc> + <type name="ParamSpecPool" c:type="GParamSpecPool*"/> + </instance-parameter> + <parameter name="owner_type" transfer-ownership="none"> + <doc xml:space="preserve">the owner to look for</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </method> + <method name="lookup" c:identifier="g_param_spec_pool_lookup"> + <doc xml:space="preserve">Looks up a #GParamSpec in the pool.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The found #GParamSpec, or %NULL if no +matching #GParamSpec was found.</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <instance-parameter name="pool" transfer-ownership="none"> + <doc xml:space="preserve">a #GParamSpecPool</doc> + <type name="ParamSpecPool" c:type="GParamSpecPool*"/> + </instance-parameter> + <parameter name="param_name" transfer-ownership="none"> + <doc xml:space="preserve">the name to look for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="owner_type" transfer-ownership="none"> + <doc xml:space="preserve">the owner to look for</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="walk_ancestors" transfer-ownership="none"> + <doc xml:space="preserve">If %TRUE, also try to find a #GParamSpec with @param_name + owned by an ancestor of @owner_type.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="remove" c:identifier="g_param_spec_pool_remove"> + <doc xml:space="preserve">Removes a #GParamSpec from the pool.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="pool" transfer-ownership="none"> + <doc xml:space="preserve">a #GParamSpecPool</doc> + <type name="ParamSpecPool" c:type="GParamSpecPool*"/> + </instance-parameter> + <parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">the #GParamSpec to remove</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </method> + <function name="new" c:identifier="g_param_spec_pool_new" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated #GParamSpecPool.</doc> + <type name="ParamSpecPool" c:type="GParamSpecPool*"/> + </return-value> + <parameters> + <parameter name="type_prefixing" transfer-ownership="none"> + <doc xml:space="preserve">Whether the pool will support type-prefixed property names.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + </record> + <class name="ParamSpecString" c:symbol-prefix="param_spec_string" c:type="GParamSpecString" parent="ParamSpec" glib:type-name="GParamString" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for string +properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="default_value"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="cset_first"> + <doc xml:space="preserve">a string containing the allowed values for the first byte</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="cset_nth"> + <doc xml:space="preserve">a string containing the allowed values for the subsequent bytes</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="substitutor"> + <doc xml:space="preserve">the replacement byte for bytes which don't match @cset_first or @cset_nth.</doc> + <type name="gchar" c:type="gchar"/> + </field> + <field name="null_fold_if_empty" bits="1"> + <doc xml:space="preserve">replace empty string by %NULL</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="ensure_non_null" bits="1"> + <doc xml:space="preserve">replace %NULL strings by an empty string</doc> + <type name="guint" c:type="guint"/> + </field> + </class> + <record name="ParamSpecTypeInfo" c:type="GParamSpecTypeInfo"> + <doc xml:space="preserve">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().</doc> + <field name="instance_size" writable="1"> + <doc xml:space="preserve">Size of the instance (object) structure.</doc> + <type name="guint16" c:type="guint16"/> + </field> + <field name="n_preallocs" writable="1"> + <doc xml:space="preserve">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.</doc> + <type name="guint16" c:type="guint16"/> + </field> + <field name="instance_init"> + <callback name="instance_init"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="value_type" writable="1"> + <doc xml:space="preserve">The #GType of values conforming to this #GParamSpec</doc> + <type name="GType" c:type="GType"/> + </field> + <field name="finalize"> + <callback name="finalize"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="value_set_default"> + <callback name="value_set_default"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="value_validate"> + <callback name="value_validate"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="values_cmp"> + <callback name="values_cmp"> + <return-value transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + <parameter name="value1" transfer-ownership="none"> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="value2" transfer-ownership="none"> + <type name="Value" c:type="const GValue*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="ParamSpecUChar" c:symbol-prefix="param_spec_uchar" c:type="GParamSpecUChar" parent="ParamSpec" glib:type-name="GParamUChar" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for unsigned character properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="minimum"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="guint8" c:type="guint8"/> + </field> + <field name="maximum"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="guint8" c:type="guint8"/> + </field> + <field name="default_value"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="guint8" c:type="guint8"/> + </field> + </class> + <class name="ParamSpecUInt" c:symbol-prefix="param_spec_uint" c:type="GParamSpecUInt" parent="ParamSpec" glib:type-name="GParamUInt" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for unsigned integer properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="minimum"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="maximum"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="default_value"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="guint" c:type="guint"/> + </field> + </class> + <class name="ParamSpecUInt64" c:symbol-prefix="param_spec_uint64" c:type="GParamSpecUInt64" parent="ParamSpec" glib:type-name="GParamUInt64" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="minimum"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="guint64" c:type="guint64"/> + </field> + <field name="maximum"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="guint64" c:type="guint64"/> + </field> + <field name="default_value"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="guint64" c:type="guint64"/> + </field> + </class> + <class name="ParamSpecULong" c:symbol-prefix="param_spec_ulong" c:type="GParamSpecULong" parent="ParamSpec" glib:type-name="GParamULong" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for unsigned long integer properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="minimum"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="gulong" c:type="gulong"/> + </field> + <field name="maximum"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="gulong" c:type="gulong"/> + </field> + <field name="default_value"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gulong" c:type="gulong"/> + </field> + </class> + <class name="ParamSpecUnichar" c:symbol-prefix="param_spec_unichar" c:type="GParamSpecUnichar" parent="ParamSpec" glib:type-name="GParamUnichar" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="default_value"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gunichar" c:type="gunichar"/> + </field> + </class> + <class name="ParamSpecValueArray" c:symbol-prefix="param_spec_value_array" c:type="GParamSpecValueArray" parent="ParamSpec" glib:type-name="GParamValueArray" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">A #GParamSpec derived structure that contains the meta data for #GValueArray properties.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="element_spec"> + <doc xml:space="preserve">a #GParamSpec describing the elements contained in arrays of this property, may be %NULL</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </field> + <field name="fixed_n_elements"> + <doc xml:space="preserve">if greater than 0, arrays of this property will always have this many elements</doc> + <type name="guint" c:type="guint"/> + </field> + </class> + <class name="ParamSpecVariant" c:symbol-prefix="param_spec_variant" c:type="GParamSpecVariant" version="2.26" parent="ParamSpec" glib:type-name="GParamVariant" glib:get-type="intern" glib:fundamental="1"> + <doc xml:space="preserve">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.</doc> + <field name="parent_instance"> + <doc xml:space="preserve">private #GParamSpec portion</doc> + <type name="ParamSpec" c:type="GParamSpec"/> + </field> + <field name="type"> + <doc xml:space="preserve">a #GVariantType, or %NULL</doc> + <type name="GLib.VariantType" c:type="GVariantType*"/> + </field> + <field name="default_value"> + <doc xml:space="preserve">a #GVariant, or %NULL</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="4"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </class> + <record name="Parameter" c:type="GParameter" deprecated="1" deprecated-version="2.54"> + <doc xml:space="preserve">The GParameter struct is an auxiliary structure used +to hand parameter name/value pairs to g_object_newv().</doc> + <doc-deprecated xml:space="preserve">This type is not introspectable.</doc-deprecated> + <field name="name" writable="1"> + <doc xml:space="preserve">the parameter name</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="value" writable="1"> + <doc xml:space="preserve">the parameter value</doc> + <type name="Value" c:type="GValue"/> + </field> + </record> + <constant name="SIGNAL_FLAGS_MASK" value="511" c:type="G_SIGNAL_FLAGS_MASK"> + <doc xml:space="preserve">A mask for all #GSignalFlags bits.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="SIGNAL_MATCH_MASK" value="63" c:type="G_SIGNAL_MATCH_MASK"> + <doc xml:space="preserve">A mask for all #GSignalMatchType bits.</doc> + <type name="gint" c:type="gint"/> + </constant> + <callback name="SignalAccumulator" c:type="GSignalAccumulator"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="ihint" transfer-ownership="none"> + <doc xml:space="preserve">Signal invocation hint, see #GSignalInvocationHint.</doc> + <type name="SignalInvocationHint" c:type="GSignalInvocationHint*"/> + </parameter> + <parameter name="return_accu" transfer-ownership="none"> + <doc xml:space="preserve">Accumulator to collect callback return values in, this + is the return value of the current signal emission.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="handler_return" transfer-ownership="none"> + <doc xml:space="preserve">A #GValue holding the return value of the signal handler.</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Callback data that was specified when creating the signal.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="SignalEmissionHook" c:type="GSignalEmissionHook"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether it wants to stay connected. If it returns %FALSE, the signal + hook is disconnected (and destroyed).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="ihint" transfer-ownership="none"> + <doc xml:space="preserve">Signal invocation hint, see #GSignalInvocationHint.</doc> + <type name="SignalInvocationHint" c:type="GSignalInvocationHint*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">the number of parameters to the function, including + the instance on which the signal was emitted.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which + the signal was emitted, followed by the parameters of the emission.</doc> + <array length="1" zero-terminated="0" c:type="const GValue*"> + <type name="Value" c:type="GValue"/> + </array> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data associated with the hook.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <bitfield name="SignalFlags" c:type="GSignalFlags"> + <doc xml:space="preserve">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.</doc> + <member name="run_first" value="1" c:identifier="G_SIGNAL_RUN_FIRST"> + <doc xml:space="preserve">Invoke the object method handler in the first emission stage.</doc> + </member> + <member name="run_last" value="2" c:identifier="G_SIGNAL_RUN_LAST"> + <doc xml:space="preserve">Invoke the object method handler in the third emission stage.</doc> + </member> + <member name="run_cleanup" value="4" c:identifier="G_SIGNAL_RUN_CLEANUP"> + <doc xml:space="preserve">Invoke the object method handler in the last emission stage.</doc> + </member> + <member name="no_recurse" value="8" c:identifier="G_SIGNAL_NO_RECURSE"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="detailed" value="16" c:identifier="G_SIGNAL_DETAILED"> + <doc xml:space="preserve">This signal supports "::detail" appendices to the signal name + upon handler connections and emissions.</doc> + </member> + <member name="action" value="32" c:identifier="G_SIGNAL_ACTION"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="no_hooks" value="64" c:identifier="G_SIGNAL_NO_HOOKS"> + <doc xml:space="preserve">No emissions hooks are supported for this signal.</doc> + </member> + <member name="must_collect" value="128" c:identifier="G_SIGNAL_MUST_COLLECT"> + <doc xml:space="preserve">Varargs signal emission will always collect the + arguments, even if there are no signal handlers connected. Since 2.30.</doc> + </member> + <member name="deprecated" value="256" c:identifier="G_SIGNAL_DEPRECATED"> + <doc xml:space="preserve">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.</doc> + </member> + </bitfield> + <record name="SignalInvocationHint" c:type="GSignalInvocationHint"> + <doc xml:space="preserve">The #GSignalInvocationHint structure is used to pass on additional information +to callbacks during a signal emission.</doc> + <field name="signal_id" writable="1"> + <doc xml:space="preserve">The signal id of the signal invoking the callback</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="detail" writable="1"> + <doc xml:space="preserve">The detail passed on for this emission</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </field> + <field name="run_type" writable="1"> + <doc xml:space="preserve">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.</doc> + <type name="SignalFlags" c:type="GSignalFlags"/> + </field> + </record> + <bitfield name="SignalMatchType" c:type="GSignalMatchType"> + <doc xml:space="preserve">The match types specify what g_signal_handlers_block_matched(), +g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() +match signals by.</doc> + <member name="id" value="1" c:identifier="G_SIGNAL_MATCH_ID"> + <doc xml:space="preserve">The signal id must be equal.</doc> + </member> + <member name="detail" value="2" c:identifier="G_SIGNAL_MATCH_DETAIL"> + <doc xml:space="preserve">The signal detail must be equal.</doc> + </member> + <member name="closure" value="4" c:identifier="G_SIGNAL_MATCH_CLOSURE"> + <doc xml:space="preserve">The closure must be the same.</doc> + </member> + <member name="func" value="8" c:identifier="G_SIGNAL_MATCH_FUNC"> + <doc xml:space="preserve">The C closure callback must be the same.</doc> + </member> + <member name="data" value="16" c:identifier="G_SIGNAL_MATCH_DATA"> + <doc xml:space="preserve">The closure data must be the same.</doc> + </member> + <member name="unblocked" value="32" c:identifier="G_SIGNAL_MATCH_UNBLOCKED"> + <doc xml:space="preserve">Only unblocked signals may be matched.</doc> + </member> + </bitfield> + <record name="SignalQuery" c:type="GSignalQuery"> + <doc xml:space="preserve">A structure holding in-depth information for a specific signal. It is +filled in by the g_signal_query() function.</doc> + <field name="signal_id" writable="1"> + <doc xml:space="preserve">The signal id of the signal being queried, or 0 if the + signal to be queried was unknown.</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="signal_name" writable="1"> + <doc xml:space="preserve">The signal name.</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="itype" writable="1"> + <doc xml:space="preserve">The interface/instance type that this signal can be emitted for.</doc> + <type name="GType" c:type="GType"/> + </field> + <field name="signal_flags" writable="1"> + <doc xml:space="preserve">The signal flags as passed in to g_signal_new().</doc> + <type name="SignalFlags" c:type="GSignalFlags"/> + </field> + <field name="return_type" writable="1"> + <doc xml:space="preserve">The return type for user callbacks.</doc> + <type name="GType" c:type="GType"/> + </field> + <field name="n_params" writable="1"> + <doc xml:space="preserve">The number of parameters that user callbacks take.</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="param_types" writable="1"> + <doc xml:space="preserve">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); + ]|</doc> + <array length="5" zero-terminated="0" c:type="const GType*"> + <type name="GType" c:type="GType"/> + </array> + </field> + </record> + <function-macro name="TYPE_CHECK_CLASS_CAST" c:identifier="G_TYPE_CHECK_CLASS_CAST" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="g_class"> + <doc xml:space="preserve">Location of a #GTypeClass structure</doc> + </parameter> + <parameter name="g_type"> + <doc xml:space="preserve">The type to be returned</doc> + </parameter> + <parameter name="c_type"> + <doc xml:space="preserve">The corresponding C type of class structure of @g_type</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_CHECK_CLASS_TYPE" c:identifier="G_TYPE_CHECK_CLASS_TYPE" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="g_class"> + <doc xml:space="preserve">Location of a #GTypeClass structure</doc> + </parameter> + <parameter name="g_type"> + <doc xml:space="preserve">The type to be checked</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_CHECK_INSTANCE" c:identifier="G_TYPE_CHECK_INSTANCE" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="instance"> + <doc xml:space="preserve">Location of a #GTypeInstance structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_CHECK_INSTANCE_CAST" c:identifier="G_TYPE_CHECK_INSTANCE_CAST" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="instance"> + <doc xml:space="preserve">Location of a #GTypeInstance structure</doc> + </parameter> + <parameter name="g_type"> + <doc xml:space="preserve">The type to be returned</doc> + </parameter> + <parameter name="c_type"> + <doc xml:space="preserve">The corresponding C type of @g_type</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_CHECK_INSTANCE_FUNDAMENTAL_TYPE" c:identifier="G_TYPE_CHECK_INSTANCE_FUNDAMENTAL_TYPE" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="instance"> + <doc xml:space="preserve">Location of a #GTypeInstance structure.</doc> + </parameter> + <parameter name="g_type"> + <doc xml:space="preserve">The fundamental type to be checked</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_CHECK_INSTANCE_TYPE" c:identifier="G_TYPE_CHECK_INSTANCE_TYPE" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="instance"> + <doc xml:space="preserve">Location of a #GTypeInstance structure.</doc> + </parameter> + <parameter name="g_type"> + <doc xml:space="preserve">The type to be checked</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_CHECK_VALUE" c:identifier="G_TYPE_CHECK_VALUE" introspectable="0"> + <doc xml:space="preserve">Checks if @value has been initialized to hold values +of a value type. + +This macro should only be used in type implementations.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a #GValue</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_CHECK_VALUE_TYPE" c:identifier="G_TYPE_CHECK_VALUE_TYPE" introspectable="0"> + <doc xml:space="preserve">Checks if @value has been initialized to hold values +of type @g_type. + +This macro should only be used in type implementations.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a #GValue</doc> + </parameter> + <parameter name="g_type"> + <doc xml:space="preserve">The type to be checked</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_CLASS_GET_PRIVATE" c:identifier="G_TYPE_CLASS_GET_PRIVATE" version="2.24" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="klass"> + <doc xml:space="preserve">the class of a type deriving from @private_type</doc> + </parameter> + <parameter name="g_type"> + <doc xml:space="preserve">the type identifying which private data to retrieve</doc> + </parameter> + <parameter name="c_type"> + <doc xml:space="preserve">The C type for the private structure</doc> + </parameter> + </parameters> + </function-macro> + <constant name="TYPE_FLAG_RESERVED_ID_BIT" value="1" c:type="G_TYPE_FLAG_RESERVED_ID_BIT"> + <doc xml:space="preserve">A bit in the type number that's supposed to be left untouched.</doc> + <type name="GLib.Type" c:type="GType"/> + </constant> + <function-macro name="TYPE_FROM_CLASS" c:identifier="G_TYPE_FROM_CLASS" introspectable="0"> + <doc xml:space="preserve">Get the type identifier from a given @class structure. + +This macro should only be used in type implementations.</doc> + <parameters> + <parameter name="g_class"> + <doc xml:space="preserve">Location of a valid #GTypeClass structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_FROM_INSTANCE" c:identifier="G_TYPE_FROM_INSTANCE" introspectable="0"> + <doc xml:space="preserve">Get the type identifier from a given @instance structure. + +This macro should only be used in type implementations.</doc> + <parameters> + <parameter name="instance"> + <doc xml:space="preserve">Location of a valid #GTypeInstance structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_FROM_INTERFACE" c:identifier="G_TYPE_FROM_INTERFACE" introspectable="0"> + <doc xml:space="preserve">Get the type identifier from a given @interface structure. + +This macro should only be used in type implementations.</doc> + <parameters> + <parameter name="g_iface"> + <doc xml:space="preserve">Location of a valid #GTypeInterface structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_FUNDAMENTAL" c:identifier="G_TYPE_FUNDAMENTAL" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">A #GType value.</doc> + </parameter> + </parameters> + </function-macro> + <constant name="TYPE_FUNDAMENTAL_MAX" value="255" c:type="G_TYPE_FUNDAMENTAL_MAX"> + <doc xml:space="preserve">An integer constant that represents the number of identifiers reserved +for types that are assigned at compile-time.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="TYPE_FUNDAMENTAL_SHIFT" value="2" c:type="G_TYPE_FUNDAMENTAL_SHIFT"> + <doc xml:space="preserve">Shift value used in converting numbers to type IDs.</doc> + <type name="gint" c:type="gint"/> + </constant> + <function-macro name="TYPE_HAS_VALUE_TABLE" c:identifier="G_TYPE_HAS_VALUE_TABLE" introspectable="0"> + <doc xml:space="preserve">Checks if @type has a #GTypeValueTable.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">A #GType value</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_INSTANCE_GET_CLASS" c:identifier="G_TYPE_INSTANCE_GET_CLASS" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="instance"> + <doc xml:space="preserve">Location of the #GTypeInstance structure</doc> + </parameter> + <parameter name="g_type"> + <doc xml:space="preserve">The #GType of the class to be returned</doc> + </parameter> + <parameter name="c_type"> + <doc xml:space="preserve">The C type of the class structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_INSTANCE_GET_INTERFACE" c:identifier="G_TYPE_INSTANCE_GET_INTERFACE" introspectable="0"> + <doc xml:space="preserve">Get the interface structure for interface @g_type of a given @instance. + +This macro should only be used in type implementations.</doc> + <parameters> + <parameter name="instance"> + <doc xml:space="preserve">Location of the #GTypeInstance structure</doc> + </parameter> + <parameter name="g_type"> + <doc xml:space="preserve">The #GType of the interface to be returned</doc> + </parameter> + <parameter name="c_type"> + <doc xml:space="preserve">The C type of the interface structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_INSTANCE_GET_PRIVATE" c:identifier="G_TYPE_INSTANCE_GET_PRIVATE" version="2.4" introspectable="0" deprecated="1" deprecated-version="2.58"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use %G_ADD_PRIVATE and the generated + `your_type_get_instance_private()` function instead</doc-deprecated> + <parameters> + <parameter name="instance"> + <doc xml:space="preserve">the instance of a type deriving from @private_type</doc> + </parameter> + <parameter name="g_type"> + <doc xml:space="preserve">the type identifying which private data to retrieve</doc> + </parameter> + <parameter name="c_type"> + <doc xml:space="preserve">The C type for the private structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_ABSTRACT" c:identifier="G_TYPE_IS_ABSTRACT" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">A #GType value</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_BOXED" c:identifier="G_TYPE_IS_BOXED" introspectable="0"> + <parameters> + <parameter name="type"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_CLASSED" c:identifier="G_TYPE_IS_CLASSED" introspectable="0"> + <doc xml:space="preserve">Checks if @type is a classed type.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">A #GType value</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_DEEP_DERIVABLE" c:identifier="G_TYPE_IS_DEEP_DERIVABLE" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">A #GType value</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_DERIVABLE" c:identifier="G_TYPE_IS_DERIVABLE" introspectable="0"> + <doc xml:space="preserve">Checks if @type is a derivable type. A derivable type can +be used as the base class of a flat (single-level) class hierarchy.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">A #GType value</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_DERIVED" c:identifier="G_TYPE_IS_DERIVED" introspectable="0"> + <doc xml:space="preserve">Checks if @type is derived (or in object-oriented terminology: +inherited) from another type (this holds true for all non-fundamental +types).</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">A #GType value</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_ENUM" c:identifier="G_TYPE_IS_ENUM" introspectable="0"> + <doc xml:space="preserve">Checks whether @type "is a" %G_TYPE_ENUM.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">a #GType ID.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_FLAGS" c:identifier="G_TYPE_IS_FLAGS" introspectable="0"> + <doc xml:space="preserve">Checks whether @type "is a" %G_TYPE_FLAGS.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">a #GType ID.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_FUNDAMENTAL" c:identifier="G_TYPE_IS_FUNDAMENTAL" introspectable="0"> + <doc xml:space="preserve">Checks if @type is a fundamental type.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">A #GType value</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_INSTANTIATABLE" c:identifier="G_TYPE_IS_INSTANTIATABLE" introspectable="0"> + <doc xml:space="preserve">Checks if @type can be instantiated. Instantiation is the +process of creating an instance (object) of this type.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">A #GType value</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_INTERFACE" c:identifier="G_TYPE_IS_INTERFACE" introspectable="0"> + <doc xml:space="preserve">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).</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">A #GType value</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_OBJECT" c:identifier="G_TYPE_IS_OBJECT" introspectable="0"> + <doc xml:space="preserve">Check if the passed in type id is a %G_TYPE_OBJECT or derived from it.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">Type id to check</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_PARAM" c:identifier="G_TYPE_IS_PARAM" introspectable="0"> + <doc xml:space="preserve">Checks whether @type "is a" %G_TYPE_PARAM.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">a #GType ID</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_VALUE" c:identifier="G_TYPE_IS_VALUE" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">A #GType value.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_VALUE_ABSTRACT" c:identifier="G_TYPE_IS_VALUE_ABSTRACT" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">A #GType value</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_VALUE_TYPE" c:identifier="G_TYPE_IS_VALUE_TYPE" introspectable="0"> + <doc xml:space="preserve">Checks if @type is a value type and can be used with g_value_init().</doc> + <parameters> + <parameter name="type"> + <doc xml:space="preserve">A #GType value</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_MAKE_FUNDAMENTAL" c:identifier="G_TYPE_MAKE_FUNDAMENTAL" introspectable="0"> + <doc xml:space="preserve">Get the type ID for the fundamental type number @x. +Use g_type_fundamental_next() instead of this macro to create new fundamental +types.</doc> + <parameters> + <parameter name="x"> + <doc xml:space="preserve">the fundamental type number.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_MODULE" c:identifier="G_TYPE_MODULE" introspectable="0"> + <parameters> + <parameter name="module"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_MODULE_CLASS" c:identifier="G_TYPE_MODULE_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_MODULE_GET_CLASS" c:identifier="G_TYPE_MODULE_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="module"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_PLUGIN" c:identifier="G_TYPE_PLUGIN" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_PLUGIN_CLASS" c:identifier="G_TYPE_PLUGIN_CLASS" introspectable="0"> + <parameters> + <parameter name="vtable"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_PLUGIN_GET_CLASS" c:identifier="G_TYPE_PLUGIN_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <constant name="TYPE_RESERVED_BSE_FIRST" value="32" c:type="G_TYPE_RESERVED_BSE_FIRST"> + <doc xml:space="preserve">First fundamental type number to create a new fundamental type id with +G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="TYPE_RESERVED_BSE_LAST" value="48" c:type="G_TYPE_RESERVED_BSE_LAST"> + <doc xml:space="preserve">Last fundamental type number reserved for BSE.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="TYPE_RESERVED_GLIB_FIRST" value="22" c:type="G_TYPE_RESERVED_GLIB_FIRST"> + <doc xml:space="preserve">First fundamental type number to create a new fundamental type id with +G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="TYPE_RESERVED_GLIB_LAST" value="31" c:type="G_TYPE_RESERVED_GLIB_LAST"> + <doc xml:space="preserve">Last fundamental type number reserved for GLib.</doc> + <type name="gint" c:type="gint"/> + </constant> + <constant name="TYPE_RESERVED_USER_FIRST" value="49" c:type="G_TYPE_RESERVED_USER_FIRST"> + <doc xml:space="preserve">First available fundamental type number to create new fundamental +type id with G_TYPE_MAKE_FUNDAMENTAL().</doc> + <type name="gint" c:type="gint"/> + </constant> + <callback name="ToggleNotify" c:type="GToggleNotify"> + <doc xml:space="preserve">A callback function used for notification when the state +of a toggle reference changes. See g_object_add_toggle_ref().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Callback data passed to g_object_add_toggle_ref()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">The object on which g_object_add_toggle_ref() was called.</doc> + <type name="Object" c:type="GObject*"/> + </parameter> + <parameter name="is_last_ref" transfer-ownership="none"> + <doc xml:space="preserve">%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.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </callback> + <union name="TypeCValue" c:type="GTypeCValue"/> + <record name="TypeClass" c:type="GTypeClass"> + <doc xml:space="preserve">An opaque structure used as the base of all classes.</doc> + <field name="g_type" readable="0" private="1"> + <type name="GType" c:type="GType"/> + </field> + <method name="add_private" c:identifier="g_type_class_add_private" version="2.4" deprecated="1" deprecated-version="2.58"> + <doc xml:space="preserve">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; +} +]|</doc> + <doc-deprecated xml:space="preserve">Use the G_ADD_PRIVATE() macro with the `G_DEFINE_*` + family of macros to add instance private data to a type</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="g_class" transfer-ownership="none"> + <doc xml:space="preserve">class structure for an instantiatable + type</doc> + <type name="TypeClass" c:type="gpointer"/> + </instance-parameter> + <parameter name="private_size" transfer-ownership="none"> + <doc xml:space="preserve">size of private structure</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <method name="get_instance_private_offset" c:identifier="g_type_class_get_instance_private_offset" version="2.38" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the offset, in bytes</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="g_class" transfer-ownership="none"> + <doc xml:space="preserve">a #GTypeClass</doc> + <type name="TypeClass" c:type="gpointer"/> + </instance-parameter> + </parameters> + </method> + <method name="get_private" c:identifier="g_type_class_get_private"> + <return-value transfer-ownership="none" nullable="1"> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="klass" transfer-ownership="none"> + <type name="TypeClass" c:type="GTypeClass*"/> + </instance-parameter> + <parameter name="private_type" transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </method> + <method name="peek_parent" c:identifier="g_type_class_peek_parent"> + <doc xml:space="preserve">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)))</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the parent class + of @g_class</doc> + <type name="TypeClass" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="g_class" transfer-ownership="none"> + <doc xml:space="preserve">the #GTypeClass structure to + retrieve the parent class for</doc> + <type name="TypeClass" c:type="gpointer"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_type_class_unref"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="g_class" transfer-ownership="none"> + <doc xml:space="preserve">a #GTypeClass structure to unref</doc> + <type name="TypeClass" c:type="gpointer"/> + </instance-parameter> + </parameters> + </method> + <method name="unref_uncached" c:identifier="g_type_class_unref_uncached" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="g_class" transfer-ownership="none"> + <doc xml:space="preserve">a #GTypeClass structure to unref</doc> + <type name="TypeClass" c:type="gpointer"/> + </instance-parameter> + </parameters> + </method> + <function name="adjust_private_offset" c:identifier="g_type_class_adjust_private_offset"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="g_class" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="private_size_or_offset" transfer-ownership="none"> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </function> + <function name="peek" c:identifier="g_type_class_peek"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GTypeClass + structure for the given type ID or %NULL if the class does not + currently exist</doc> + <type name="TypeClass" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">type ID of a classed type</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="peek_static" c:identifier="g_type_class_peek_static" version="2.4"> + <doc xml:space="preserve">A more efficient version of g_type_class_peek() which works only for +static types.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GTypeClass + structure for the given type ID or %NULL if the class does not + currently exist or is dynamically loaded</doc> + <type name="TypeClass" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">type ID of a classed type</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="ref" c:identifier="g_type_class_ref"> + <doc xml:space="preserve">Increments the reference count of the class structure belonging to +@type. This function will demand-create the class if it doesn't +exist already.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GTypeClass + structure for the given type ID</doc> + <type name="TypeClass" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">type ID of a classed type</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + </record> + <callback name="TypeClassCacheFunc" c:type="GTypeClassCacheFunc"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop further #GTypeClassCacheFuncs from being + called, %FALSE to continue</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="cache_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data that was given to the g_type_add_class_cache_func() call</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="g_class" transfer-ownership="none"> + <doc xml:space="preserve">The #GTypeClass structure which is + unreferenced</doc> + <type name="TypeClass" c:type="GTypeClass*"/> + </parameter> + </parameters> + </callback> + <bitfield name="TypeDebugFlags" deprecated="1" deprecated-version="2.36" c:type="GTypeDebugFlags"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">g_type_init() is now done automatically</doc-deprecated> + <member name="none" value="0" c:identifier="G_TYPE_DEBUG_NONE"> + <doc xml:space="preserve">Print no messages</doc> + </member> + <member name="objects" value="1" c:identifier="G_TYPE_DEBUG_OBJECTS"> + <doc xml:space="preserve">Print messages about object bookkeeping</doc> + </member> + <member name="signals" value="2" c:identifier="G_TYPE_DEBUG_SIGNALS"> + <doc xml:space="preserve">Print messages about signal emissions</doc> + </member> + <member name="instance_count" value="4" c:identifier="G_TYPE_DEBUG_INSTANCE_COUNT"> + <doc xml:space="preserve">Keep a count of instances of each type</doc> + </member> + <member name="mask" value="7" c:identifier="G_TYPE_DEBUG_MASK"> + <doc xml:space="preserve">Mask covering all debug flags</doc> + </member> + </bitfield> + <bitfield name="TypeFlags" c:type="GTypeFlags"> + <doc xml:space="preserve">Bit masks used to check or determine characteristics of a type.</doc> + <member name="abstract" value="16" c:identifier="G_TYPE_FLAG_ABSTRACT"> + <doc xml:space="preserve">Indicates an abstract type. No instances can be + created for an abstract type</doc> + </member> + <member name="value_abstract" value="32" c:identifier="G_TYPE_FLAG_VALUE_ABSTRACT"> + <doc xml:space="preserve">Indicates an abstract value type, i.e. a type + that introduces a value table, but can't be used for + g_value_init()</doc> + </member> + </bitfield> + <bitfield name="TypeFundamentalFlags" c:type="GTypeFundamentalFlags"> + <doc xml:space="preserve">Bit masks used to check or determine specific characteristics of a +fundamental type.</doc> + <member name="classed" value="1" c:identifier="G_TYPE_FLAG_CLASSED"> + <doc xml:space="preserve">Indicates a classed type</doc> + </member> + <member name="instantiatable" value="2" c:identifier="G_TYPE_FLAG_INSTANTIATABLE"> + <doc xml:space="preserve">Indicates an instantiable type (implies classed)</doc> + </member> + <member name="derivable" value="4" c:identifier="G_TYPE_FLAG_DERIVABLE"> + <doc xml:space="preserve">Indicates a flat derivable type</doc> + </member> + <member name="deep_derivable" value="8" c:identifier="G_TYPE_FLAG_DEEP_DERIVABLE"> + <doc xml:space="preserve">Indicates a deep derivable type (implies derivable)</doc> + </member> + </bitfield> + <record name="TypeFundamentalInfo" c:type="GTypeFundamentalInfo"> + <doc xml:space="preserve">A structure that provides information to the type system which is +used specifically for managing fundamental types.</doc> + <field name="type_flags" writable="1"> + <doc xml:space="preserve">#GTypeFundamentalFlags describing the characteristics of the fundamental type</doc> + <type name="TypeFundamentalFlags" c:type="GTypeFundamentalFlags"/> + </field> + </record> + <record name="TypeInfo" c:type="GTypeInfo"> + <doc xml:space="preserve">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().</doc> + <field name="class_size" writable="1"> + <doc xml:space="preserve">Size of the class structure (required for interface, classed and instantiatable types)</doc> + <type name="guint16" c:type="guint16"/> + </field> + <field name="base_init" writable="1"> + <doc xml:space="preserve">Location of the base initialization function (optional)</doc> + <type name="BaseInitFunc" c:type="GBaseInitFunc"/> + </field> + <field name="base_finalize" writable="1"> + <doc xml:space="preserve">Location of the base finalization function (optional)</doc> + <type name="BaseFinalizeFunc" c:type="GBaseFinalizeFunc"/> + </field> + <field name="class_init" writable="1"> + <doc xml:space="preserve">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.</doc> + <type name="ClassInitFunc" c:type="GClassInitFunc"/> + </field> + <field name="class_finalize" writable="1"> + <doc xml:space="preserve">Location of the class finalization function for + classed and instantiatable types. Location of the default vtable + finalization function for interface types. (optional)</doc> + <type name="ClassFinalizeFunc" c:type="GClassFinalizeFunc"/> + </field> + <field name="class_data" writable="1"> + <doc xml:space="preserve">User-supplied data passed to the class init/finalize functions</doc> + <type name="gpointer" c:type="gconstpointer"/> + </field> + <field name="instance_size" writable="1"> + <doc xml:space="preserve">Size of the instance (object) structure (required for instantiatable types only)</doc> + <type name="guint16" c:type="guint16"/> + </field> + <field name="n_preallocs" writable="1"> + <doc xml:space="preserve">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.</doc> + <type name="guint16" c:type="guint16"/> + </field> + <field name="instance_init" writable="1"> + <doc xml:space="preserve">Location of the instance initialization function (optional, for instantiatable types only)</doc> + <type name="InstanceInitFunc" c:type="GInstanceInitFunc"/> + </field> + <field name="value_table" writable="1"> + <doc xml:space="preserve">A #GTypeValueTable function table for generic handling of GValues + of this type (usually only useful for fundamental types)</doc> + <type name="TypeValueTable" c:type="const GTypeValueTable*"/> + </field> + </record> + <record name="TypeInstance" c:type="GTypeInstance"> + <doc xml:space="preserve">An opaque structure used as the base of all type instances.</doc> + <field name="g_class" readable="0" private="1"> + <type name="TypeClass" c:type="GTypeClass*"/> + </field> + <method name="get_private" c:identifier="g_type_instance_get_private"> + <return-value transfer-ownership="none" nullable="1"> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="instance" transfer-ownership="none"> + <type name="TypeInstance" c:type="GTypeInstance*"/> + </instance-parameter> + <parameter name="private_type" transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </method> + </record> + <record name="TypeInterface" c:type="GTypeInterface"> + <doc xml:space="preserve">An opaque structure used as the base of all interface types.</doc> + <field name="g_type" readable="0" private="1"> + <type name="GType" c:type="GType"/> + </field> + <field name="g_instance_type" readable="0" private="1"> + <type name="GType" c:type="GType"/> + </field> + <method name="peek_parent" c:identifier="g_type_interface_peek_parent"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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</doc> + <type name="TypeInterface" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="g_iface" transfer-ownership="none"> + <doc xml:space="preserve">a #GTypeInterface structure</doc> + <type name="TypeInterface" c:type="gpointer"/> + </instance-parameter> + </parameters> + </method> + <function name="add_prerequisite" c:identifier="g_type_interface_add_prerequisite"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="interface_type" transfer-ownership="none"> + <doc xml:space="preserve">#GType value of an interface type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="prerequisite_type" transfer-ownership="none"> + <doc xml:space="preserve">#GType value of an interface or instantiatable type</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="get_plugin" c:identifier="g_type_interface_get_plugin"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GTypePlugin for the dynamic + interface @interface_type of @instance_type</doc> + <type name="TypePlugin" c:type="GTypePlugin*"/> + </return-value> + <parameters> + <parameter name="instance_type" transfer-ownership="none"> + <doc xml:space="preserve">#GType of an instantiatable type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="interface_type" transfer-ownership="none"> + <doc xml:space="preserve">#GType of an interface type</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="peek" c:identifier="g_type_interface_peek"> + <doc xml:space="preserve">Returns the #GTypeInterface structure of an interface to which the +passed in class conforms.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GTypeInterface + structure of @iface_type if implemented by @instance_class, %NULL + otherwise</doc> + <type name="TypeInterface" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="instance_class" transfer-ownership="none"> + <doc xml:space="preserve">a #GTypeClass structure</doc> + <type name="TypeClass" c:type="gpointer"/> + </parameter> + <parameter name="iface_type" transfer-ownership="none"> + <doc xml:space="preserve">an interface ID which this class conforms to</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="prerequisites" c:identifier="g_type_interface_prerequisites" version="2.2"> + <doc xml:space="preserve">Returns the prerequisites of an interfaces type.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a + newly-allocated zero-terminated array of #GType containing + the prerequisites of @interface_type</doc> + <array length="1" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </return-value> + <parameters> + <parameter name="interface_type" transfer-ownership="none"> + <doc xml:space="preserve">an interface type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_prerequisites" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to return the number + of prerequisites, or %NULL</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </function> + </record> + <callback name="TypeInterfaceCheckFunc" c:type="GTypeInterfaceCheckFunc" version="2.4"> + <doc xml:space="preserve">A callback called after an interface vtable is initialized. +See g_type_add_interface_check().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="check_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data passed to g_type_add_interface_check()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="g_iface" transfer-ownership="none"> + <doc xml:space="preserve">the interface that has been + initialized</doc> + <type name="TypeInterface" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <class name="TypeModule" c:symbol-prefix="type_module" c:type="GTypeModule" parent="Object" abstract="1" glib:type-name="GTypeModule" glib:get-type="g_type_module_get_type" glib:type-struct="TypeModuleClass"> + <doc xml:space="preserve">#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.</doc> + <implements name="TypePlugin"/> + <virtual-method name="load"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="module" transfer-ownership="none"> + <type name="TypeModule" c:type="GTypeModule*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="unload"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="module" transfer-ownership="none"> + <type name="TypeModule" c:type="GTypeModule*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="add_interface" c:identifier="g_type_module_add_interface"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="module" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GTypeModule</doc> + <type name="TypeModule" c:type="GTypeModule*"/> + </instance-parameter> + <parameter name="instance_type" transfer-ownership="none"> + <doc xml:space="preserve">type to which to add the interface.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="interface_type" transfer-ownership="none"> + <doc xml:space="preserve">interface type to add</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="interface_info" transfer-ownership="none"> + <doc xml:space="preserve">type information structure</doc> + <type name="InterfaceInfo" c:type="const GInterfaceInfo*"/> + </parameter> + </parameters> + </method> + <method name="register_enum" c:identifier="g_type_module_register_enum" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the new or existing type ID</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <instance-parameter name="module" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GTypeModule</doc> + <type name="TypeModule" c:type="GTypeModule*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">name for the type</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="const_static_values" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GEnumValue structs for the + possible enumeration values. The array is + terminated by a struct with all members being + 0.</doc> + <type name="EnumValue" c:type="const GEnumValue*"/> + </parameter> + </parameters> + </method> + <method name="register_flags" c:identifier="g_type_module_register_flags" version="2.6"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the new or existing type ID</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <instance-parameter name="module" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GTypeModule</doc> + <type name="TypeModule" c:type="GTypeModule*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">name for the type</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="const_static_values" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GFlagsValue structs for the + possible flags values. The array is + terminated by a struct with all members being + 0.</doc> + <type name="FlagsValue" c:type="const GFlagsValue*"/> + </parameter> + </parameters> + </method> + <method name="register_type" c:identifier="g_type_module_register_type"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the new or existing type ID</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <instance-parameter name="module" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GTypeModule</doc> + <type name="TypeModule" c:type="GTypeModule*"/> + </instance-parameter> + <parameter name="parent_type" transfer-ownership="none"> + <doc xml:space="preserve">the type for the parent class</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="type_name" transfer-ownership="none"> + <doc xml:space="preserve">name for the type</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="type_info" transfer-ownership="none"> + <doc xml:space="preserve">type information structure</doc> + <type name="TypeInfo" c:type="const GTypeInfo*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags field providing details about the type</doc> + <type name="TypeFlags" c:type="GTypeFlags"/> + </parameter> + </parameters> + </method> + <method name="set_name" c:identifier="g_type_module_set_name"> + <doc xml:space="preserve">Sets the name for a #GTypeModule</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="module" transfer-ownership="none"> + <doc xml:space="preserve">a #GTypeModule.</doc> + <type name="TypeModule" c:type="GTypeModule*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">a human-readable name to use in error messages.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="unuse" c:identifier="g_type_module_unuse"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="module" transfer-ownership="none"> + <doc xml:space="preserve">a #GTypeModule</doc> + <type name="TypeModule" c:type="GTypeModule*"/> + </instance-parameter> + </parameters> + </method> + <method name="use" c:identifier="g_type_module_use"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%FALSE if the plugin needed to be loaded and + loading the plugin failed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="module" transfer-ownership="none"> + <doc xml:space="preserve">a #GTypeModule</doc> + <type name="TypeModule" c:type="GTypeModule*"/> + </instance-parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="Object" c:type="GObject"/> + </field> + <field name="use_count"> + <type name="guint" c:type="guint"/> + </field> + <field name="type_infos"> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </field> + <field name="interface_infos"> + <type name="GLib.SList" c:type="GSList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </field> + <field name="name"> + <doc xml:space="preserve">the name of the module</doc> + <type name="utf8" c:type="gchar*"/> + </field> + </class> + <record name="TypeModuleClass" c:type="GTypeModuleClass" glib:is-gtype-struct-for="TypeModule"> + <doc xml:space="preserve">In order to implement dynamic loading of types based on #GTypeModule, +the @load and @unload functions in #GTypeModuleClass must be implemented.</doc> + <field name="parent_class"> + <doc xml:space="preserve">the parent class</doc> + <type name="ObjectClass" c:type="GObjectClass"/> + </field> + <field name="load"> + <callback name="load"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="module" transfer-ownership="none"> + <type name="TypeModule" c:type="GTypeModule*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="unload"> + <callback name="unload"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="module" transfer-ownership="none"> + <type name="TypeModule" c:type="GTypeModule*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="reserved1"> + <callback name="reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="reserved2"> + <callback name="reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="reserved3"> + <callback name="reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="reserved4"> + <callback name="reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <interface name="TypePlugin" c:symbol-prefix="type_plugin" c:type="GTypePlugin" glib:type-name="GTypePlugin" glib:get-type="g_type_plugin_get_type"> + <doc xml:space="preserve">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.</doc> + <method name="complete_interface_info" c:identifier="g_type_plugin_complete_interface_info"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="plugin" transfer-ownership="none"> + <doc xml:space="preserve">the #GTypePlugin</doc> + <type name="TypePlugin" c:type="GTypePlugin*"/> + </instance-parameter> + <parameter name="instance_type" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of an instantiatable type to which the interface + is added</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="interface_type" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of the interface whose info is completed</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">the #GInterfaceInfo to fill in</doc> + <type name="InterfaceInfo" c:type="GInterfaceInfo*"/> + </parameter> + </parameters> + </method> + <method name="complete_type_info" c:identifier="g_type_plugin_complete_type_info"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="plugin" transfer-ownership="none"> + <doc xml:space="preserve">a #GTypePlugin</doc> + <type name="TypePlugin" c:type="GTypePlugin*"/> + </instance-parameter> + <parameter name="g_type" transfer-ownership="none"> + <doc xml:space="preserve">the #GType whose info is completed</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">the #GTypeInfo struct to fill in</doc> + <type name="TypeInfo" c:type="GTypeInfo*"/> + </parameter> + <parameter name="value_table" transfer-ownership="none"> + <doc xml:space="preserve">the #GTypeValueTable to fill in</doc> + <type name="TypeValueTable" c:type="GTypeValueTable*"/> + </parameter> + </parameters> + </method> + <method name="unuse" c:identifier="g_type_plugin_unuse"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="plugin" transfer-ownership="none"> + <doc xml:space="preserve">a #GTypePlugin</doc> + <type name="TypePlugin" c:type="GTypePlugin*"/> + </instance-parameter> + </parameters> + </method> + <method name="use" c:identifier="g_type_plugin_use"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="plugin" transfer-ownership="none"> + <doc xml:space="preserve">a #GTypePlugin</doc> + <type name="TypePlugin" c:type="GTypePlugin*"/> + </instance-parameter> + </parameters> + </method> + </interface> + <record name="TypePluginClass" c:type="GTypePluginClass"> + <doc xml:space="preserve">The #GTypePlugin interface is used by the type system in order to handle +the lifecycle of dynamically loaded types.</doc> + <field name="base_iface" readable="0" private="1"> + <type name="TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="use_plugin" writable="1"> + <doc xml:space="preserve">Increases the use count of the plugin.</doc> + <type name="TypePluginUse" c:type="GTypePluginUse"/> + </field> + <field name="unuse_plugin" writable="1"> + <doc xml:space="preserve">Decreases the use count of the plugin.</doc> + <type name="TypePluginUnuse" c:type="GTypePluginUnuse"/> + </field> + <field name="complete_type_info" writable="1"> + <doc xml:space="preserve">Fills in the #GTypeInfo and + #GTypeValueTable structs for the type. The structs are initialized + with `memset(s, 0, sizeof (s))` before calling this function.</doc> + <type name="TypePluginCompleteTypeInfo" c:type="GTypePluginCompleteTypeInfo"/> + </field> + <field name="complete_interface_info" writable="1"> + <doc xml:space="preserve">Fills in missing parts of the #GInterfaceInfo + for the interface. The structs is initialized with + `memset(s, 0, sizeof (s))` before calling this function.</doc> + <type name="TypePluginCompleteInterfaceInfo" c:type="GTypePluginCompleteInterfaceInfo"/> + </field> + </record> + <callback name="TypePluginCompleteInterfaceInfo" c:type="GTypePluginCompleteInterfaceInfo"> + <doc xml:space="preserve">The type of the @complete_interface_info function of #GTypePluginClass.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="plugin" transfer-ownership="none"> + <doc xml:space="preserve">the #GTypePlugin</doc> + <type name="TypePlugin" c:type="GTypePlugin*"/> + </parameter> + <parameter name="instance_type" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of an instantiable type to which the interface + is added</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="interface_type" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of the interface whose info is completed</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">the #GInterfaceInfo to fill in</doc> + <type name="InterfaceInfo" c:type="GInterfaceInfo*"/> + </parameter> + </parameters> + </callback> + <callback name="TypePluginCompleteTypeInfo" c:type="GTypePluginCompleteTypeInfo"> + <doc xml:space="preserve">The type of the @complete_type_info function of #GTypePluginClass.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="plugin" transfer-ownership="none"> + <doc xml:space="preserve">the #GTypePlugin</doc> + <type name="TypePlugin" c:type="GTypePlugin*"/> + </parameter> + <parameter name="g_type" transfer-ownership="none"> + <doc xml:space="preserve">the #GType whose info is completed</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">the #GTypeInfo struct to fill in</doc> + <type name="TypeInfo" c:type="GTypeInfo*"/> + </parameter> + <parameter name="value_table" transfer-ownership="none"> + <doc xml:space="preserve">the #GTypeValueTable to fill in</doc> + <type name="TypeValueTable" c:type="GTypeValueTable*"/> + </parameter> + </parameters> + </callback> + <callback name="TypePluginUnuse" c:type="GTypePluginUnuse"> + <doc xml:space="preserve">The type of the @unuse_plugin function of #GTypePluginClass.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="plugin" transfer-ownership="none"> + <doc xml:space="preserve">the #GTypePlugin whose use count should be decreased</doc> + <type name="TypePlugin" c:type="GTypePlugin*"/> + </parameter> + </parameters> + </callback> + <callback name="TypePluginUse" c:type="GTypePluginUse"> + <doc xml:space="preserve">The type of the @use_plugin function of #GTypePluginClass, which gets called +to increase the use count of @plugin.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="plugin" transfer-ownership="none"> + <doc xml:space="preserve">the #GTypePlugin whose use count should be increased</doc> + <type name="TypePlugin" c:type="GTypePlugin*"/> + </parameter> + </parameters> + </callback> + <record name="TypeQuery" c:type="GTypeQuery"> + <doc xml:space="preserve">A structure holding information for a specific type. +It is filled in by the g_type_query() function.</doc> + <field name="type" writable="1"> + <doc xml:space="preserve">the #GType value of the type</doc> + <type name="GType" c:type="GType"/> + </field> + <field name="type_name" writable="1"> + <doc xml:space="preserve">the name of the type</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="class_size" writable="1"> + <doc xml:space="preserve">the size of the class structure</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="instance_size" writable="1"> + <doc xml:space="preserve">the size of the instance structure</doc> + <type name="guint" c:type="guint"/> + </field> + </record> + <record name="TypeValueTable" c:type="GTypeValueTable"> + <doc xml:space="preserve">The #GTypeValueTable provides the functions required by the #GValue +implementation, to serve as a container for values of a type.</doc> + <field name="value_init"> + <callback name="value_init"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="value_free"> + <callback name="value_free"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="value_copy"> + <callback name="value_copy"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="src_value" transfer-ownership="none"> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="dest_value" transfer-ownership="none"> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="value_peek_pointer"> + <callback name="value_peek_pointer"> + <return-value transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="const GValue*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="collect_format" writable="1"> + <doc xml:space="preserve">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'.</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="collect_value"> + <callback name="collect_value"> + <return-value transfer-ownership="full"> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_collect_values" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="collect_values" transfer-ownership="none"> + <type name="TypeCValue" c:type="GTypeCValue*"/> + </parameter> + <parameter name="collect_flags" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lcopy_format" writable="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="lcopy_value"> + <callback name="lcopy_value"> + <return-value transfer-ownership="full"> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="n_collect_values" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="collect_values" transfer-ownership="none"> + <type name="TypeCValue" c:type="GTypeCValue*"/> + </parameter> + <parameter name="collect_flags" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </callback> + </field> + <function name="peek" c:identifier="g_type_value_table_peek" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">location of the #GTypeValueTable associated with @type or + %NULL if there is no #GTypeValueTable associated with @type</doc> + <type name="TypeValueTable" c:type="GTypeValueTable*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + </record> + <function-macro name="VALUE_HOLDS" c:identifier="G_VALUE_HOLDS" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">A #GValue structure.</doc> + </parameter> + <parameter name="type"> + <doc xml:space="preserve">A #GType value.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_BOOLEAN" c:identifier="G_VALUE_HOLDS_BOOLEAN" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_BOXED" c:identifier="G_VALUE_HOLDS_BOXED" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values derived +from type %G_TYPE_BOXED.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_CHAR" c:identifier="G_VALUE_HOLDS_CHAR" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values of type %G_TYPE_CHAR.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_DOUBLE" c:identifier="G_VALUE_HOLDS_DOUBLE" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_ENUM" c:identifier="G_VALUE_HOLDS_ENUM" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_FLAGS" c:identifier="G_VALUE_HOLDS_FLAGS" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_FLOAT" c:identifier="G_VALUE_HOLDS_FLOAT" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_GTYPE" c:identifier="G_VALUE_HOLDS_GTYPE" version="2.12" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_INT" c:identifier="G_VALUE_HOLDS_INT" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values of type %G_TYPE_INT.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_INT64" c:identifier="G_VALUE_HOLDS_INT64" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values of type %G_TYPE_INT64.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_LONG" c:identifier="G_VALUE_HOLDS_LONG" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values of type %G_TYPE_LONG.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_OBJECT" c:identifier="G_VALUE_HOLDS_OBJECT" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_PARAM" c:identifier="G_VALUE_HOLDS_PARAM" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_POINTER" c:identifier="G_VALUE_HOLDS_POINTER" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values of type %G_TYPE_POINTER.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_STRING" c:identifier="G_VALUE_HOLDS_STRING" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values of type %G_TYPE_STRING.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_UCHAR" c:identifier="G_VALUE_HOLDS_UCHAR" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_UINT" c:identifier="G_VALUE_HOLDS_UINT" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values of type %G_TYPE_UINT.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_UINT64" c:identifier="G_VALUE_HOLDS_UINT64" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values of type %G_TYPE_UINT64.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_ULONG" c:identifier="G_VALUE_HOLDS_ULONG" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values of type %G_TYPE_ULONG.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_HOLDS_VARIANT" c:identifier="G_VALUE_HOLDS_VARIANT" version="2.26" introspectable="0"> + <doc xml:space="preserve">Checks whether the given #GValue can hold values of type %G_TYPE_VARIANT.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <constant name="VALUE_INTERNED_STRING" value="268435456" c:type="G_VALUE_INTERNED_STRING" version="2.66"> + <doc xml:space="preserve">For string values, indicates that the string contained is canonical and will +exist for the duration of the process. See g_value_set_interned_string().</doc> + <type name="gint" c:type="gint"/> + </constant> + <function-macro name="VALUE_IS_INTERNED_STRING" c:identifier="G_VALUE_IS_INTERNED_STRING" version="2.66" introspectable="0"> + <doc xml:space="preserve">Checks whether @value contains a string which is canonical.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">a valid #GValue structure</doc> + </parameter> + </parameters> + </function-macro> + <constant name="VALUE_NOCOPY_CONTENTS" value="134217728" c:type="G_VALUE_NOCOPY_CONTENTS"> + <doc xml:space="preserve">If passed to G_VALUE_COLLECT(), allocated data won't be copied +but used verbatim. This does not affect ref-counted types like +objects. This does not affect usage of g_value_copy(), the data will +be copied if it is not ref-counted.</doc> + <type name="gint" c:type="gint"/> + </constant> + <function-macro name="VALUE_TYPE" c:identifier="G_VALUE_TYPE" introspectable="0"> + <doc xml:space="preserve">Get the type identifier of @value.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">A #GValue structure.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="VALUE_TYPE_NAME" c:identifier="G_VALUE_TYPE_NAME" introspectable="0"> + <doc xml:space="preserve">Gets the type name of @value.</doc> + <parameters> + <parameter name="value"> + <doc xml:space="preserve">A #GValue structure.</doc> + </parameter> + </parameters> + </function-macro> + <callback name="VaClosureMarshal" c:type="GVaClosureMarshal" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance on which the closure is + invoked.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments to be passed to the closure.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @param_types array</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="param_types" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of each argument from + @args.</doc> + <array length="5" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </callback> + <record name="Value" c:type="GValue" glib:type-name="GValue" glib:get-type="g_value_get_type" c:symbol-prefix="value"> + <doc xml:space="preserve">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.</doc> + <field name="g_type" readable="0" private="1"> + <type name="GType" c:type="GType"/> + </field> + <field name="data" writable="1"> + <array zero-terminated="0" fixed-size="2"> + <type name="_Value__data__union"/> + </array> + </field> + <method name="copy" c:identifier="g_value_copy"> + <doc xml:space="preserve">Copies the value of @src_value into @dest_value.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="src_value" transfer-ownership="none"> + <doc xml:space="preserve">An initialized #GValue structure.</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + <parameter name="dest_value" transfer-ownership="none"> + <doc xml:space="preserve">An initialized #GValue structure of the same type as @src_value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </method> + <method name="dup_boxed" c:identifier="g_value_dup_boxed" introspectable="0"> + <doc xml:space="preserve">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);</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">boxed contents of @value</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of %G_TYPE_BOXED derived type</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="dup_object" c:identifier="g_value_dup_object"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">object content of @value, + should be unreferenced when no longer needed.</doc> + <type name="Object" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue whose type is derived from %G_TYPE_OBJECT</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="dup_param" c:identifier="g_value_dup_param" introspectable="0"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_PARAM #GValue, increasing its +reference count.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GParamSpec content of @value, should be + unreferenced when no longer needed.</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue whose type is derived from %G_TYPE_PARAM</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="dup_string" c:identifier="g_value_dup_string"> + <doc xml:space="preserve">Get a copy the contents of a %G_TYPE_STRING #GValue.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated copy of the string content of @value</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_STRING</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="dup_variant" c:identifier="g_value_dup_variant" version="2.26"> + <doc xml:space="preserve">Get the contents of a variant #GValue, increasing its refcount. The returned +#GVariant is never floating.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">variant contents of @value (may be %NULL); + should be unreffed using g_variant_unref() when no longer needed</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_VARIANT</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="fits_pointer" c:identifier="g_value_fits_pointer"> + <doc xml:space="preserve">Determines if @value will fit inside the size of a pointer value. +This is an internal function introduced mainly for C marshallers.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @value will fit inside a pointer value.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">An initialized #GValue structure.</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_boolean" c:identifier="g_value_get_boolean"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_BOOLEAN #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">boolean contents of @value</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_BOOLEAN</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_boxed" c:identifier="g_value_get_boxed"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_BOXED derived #GValue.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">boxed contents of @value</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of %G_TYPE_BOXED derived type</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_char" c:identifier="g_value_get_char" deprecated="1" deprecated-version="2.32"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">This function's return type is broken, see g_value_get_schar()</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">character contents of @value</doc> + <type name="gchar" c:type="gchar"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_CHAR</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_double" c:identifier="g_value_get_double"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_DOUBLE #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">double contents of @value</doc> + <type name="gdouble" c:type="gdouble"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_DOUBLE</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_enum" c:identifier="g_value_get_enum"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_ENUM #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">enum contents of @value</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue whose type is derived from %G_TYPE_ENUM</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_flags" c:identifier="g_value_get_flags"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_FLAGS #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">flags contents of @value</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue whose type is derived from %G_TYPE_FLAGS</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_float" c:identifier="g_value_get_float"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_FLOAT #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">float contents of @value</doc> + <type name="gfloat" c:type="gfloat"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_FLOAT</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_gtype" c:identifier="g_value_get_gtype" version="2.12"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_GTYPE #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GType stored in @value</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_GTYPE</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_int" c:identifier="g_value_get_int"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_INT #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">integer contents of @value</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_INT</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_int64" c:identifier="g_value_get_int64"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_INT64 #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">64bit integer contents of @value</doc> + <type name="gint64" c:type="gint64"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_INT64</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_long" c:identifier="g_value_get_long"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_LONG #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">long integer contents of @value</doc> + <type name="glong" c:type="glong"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_LONG</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_object" c:identifier="g_value_get_object"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_OBJECT derived #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">object contents of @value</doc> + <type name="Object" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of %G_TYPE_OBJECT derived type</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_param" c:identifier="g_value_get_param"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_PARAM #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">#GParamSpec content of @value</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue whose type is derived from %G_TYPE_PARAM</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_pointer" c:identifier="g_value_get_pointer"> + <doc xml:space="preserve">Get the contents of a pointer #GValue.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">pointer contents of @value</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of %G_TYPE_POINTER</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_schar" c:identifier="g_value_get_schar" version="2.32"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_CHAR #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">signed 8 bit integer contents of @value</doc> + <type name="gint8" c:type="gint8"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_CHAR</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_string" c:identifier="g_value_get_string"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_STRING #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">string content of @value</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_STRING</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_uchar" c:identifier="g_value_get_uchar"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_UCHAR #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">unsigned character contents of @value</doc> + <type name="guint8" c:type="guchar"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_UCHAR</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_uint" c:identifier="g_value_get_uint"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_UINT #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">unsigned integer contents of @value</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_UINT</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_uint64" c:identifier="g_value_get_uint64"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_UINT64 #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">unsigned 64bit integer contents of @value</doc> + <type name="guint64" c:type="guint64"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_UINT64</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_ulong" c:identifier="g_value_get_ulong"> + <doc xml:space="preserve">Get the contents of a %G_TYPE_ULONG #GValue.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">unsigned long integer contents of @value</doc> + <type name="gulong" c:type="gulong"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_ULONG</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_variant" c:identifier="g_value_get_variant" version="2.26"> + <doc xml:space="preserve">Get the contents of a variant #GValue.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">variant contents of @value (may be %NULL)</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_VARIANT</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="init" c:identifier="g_value_init"> + <doc xml:space="preserve">Initializes @value with the default value of @type.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GValue structure that has been passed in</doc> + <type name="Value" c:type="GValue*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">A zero-filled (uninitialized) #GValue structure.</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="g_type" transfer-ownership="none"> + <doc xml:space="preserve">Type the #GValue should hold values of.</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </method> + <method name="init_from_instance" c:identifier="g_value_init_from_instance" version="2.42"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">An uninitialized #GValue structure.</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="peek_pointer" c:identifier="g_value_peek_pointer"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the value contents as pointer</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">An initialized #GValue structure</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="reset" c:identifier="g_value_reset"> + <doc xml:space="preserve">Clears the current value in @value and resets it to the default value +(as if the value had just been initialized).</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the #GValue structure that has been passed in</doc> + <type name="Value" c:type="GValue*"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">An initialized #GValue structure.</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_boolean" c:identifier="g_value_set_boolean"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_BOOLEAN</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_boolean" transfer-ownership="none"> + <doc xml:space="preserve">boolean value to be set</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_boxed" c:identifier="g_value_set_boxed"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of %G_TYPE_BOXED derived type</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_boxed" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">boxed value to be set</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="set_boxed_take_ownership" c:identifier="g_value_set_boxed_take_ownership" deprecated="1" deprecated-version="2.4"> + <doc xml:space="preserve">This is an internal function introduced mainly for C marshallers.</doc> + <doc-deprecated xml:space="preserve">Use g_value_take_boxed() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of %G_TYPE_BOXED derived type</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_boxed" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">duplicated unowned boxed value to be set</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="set_char" c:identifier="g_value_set_char" deprecated="1" deprecated-version="2.32"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_CHAR #GValue to @v_char.</doc> + <doc-deprecated xml:space="preserve">This function's input type is broken, see g_value_set_schar()</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_CHAR</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_char" transfer-ownership="none"> + <doc xml:space="preserve">character value to be set</doc> + <type name="gchar" c:type="gchar"/> + </parameter> + </parameters> + </method> + <method name="set_double" c:identifier="g_value_set_double"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_DOUBLE</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_double" transfer-ownership="none"> + <doc xml:space="preserve">double value to be set</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + </parameters> + </method> + <method name="set_enum" c:identifier="g_value_set_enum"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_ENUM #GValue to @v_enum.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue whose type is derived from %G_TYPE_ENUM</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_enum" transfer-ownership="none"> + <doc xml:space="preserve">enum value to be set</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="set_flags" c:identifier="g_value_set_flags"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue whose type is derived from %G_TYPE_FLAGS</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_flags" transfer-ownership="none"> + <doc xml:space="preserve">flags value to be set</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="set_float" c:identifier="g_value_set_float"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_FLOAT #GValue to @v_float.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_FLOAT</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_float" transfer-ownership="none"> + <doc xml:space="preserve">float value to be set</doc> + <type name="gfloat" c:type="gfloat"/> + </parameter> + </parameters> + </method> + <method name="set_gtype" c:identifier="g_value_set_gtype" version="2.12"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_GTYPE</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_gtype" transfer-ownership="none"> + <doc xml:space="preserve">#GType to be set</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </method> + <method name="set_instance" c:identifier="g_value_set_instance"> + <doc xml:space="preserve">Sets @value from an instantiatable type via the +value_table's collect_value() function.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">An initialized #GValue structure.</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="instance" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the instance</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="set_int" c:identifier="g_value_set_int"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_INT #GValue to @v_int.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_INT</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_int" transfer-ownership="none"> + <doc xml:space="preserve">integer value to be set</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="set_int64" c:identifier="g_value_set_int64"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_INT64 #GValue to @v_int64.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_INT64</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_int64" transfer-ownership="none"> + <doc xml:space="preserve">64bit integer value to be set</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + </parameters> + </method> + <method name="set_interned_string" c:identifier="g_value_set_interned_string" version="2.66"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_STRING #GValue to @v_string. The string is +assumed to be static and interned (canonical, for example from +g_intern_string()), and is thus not duplicated when setting the #GValue.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_STRING</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">static string to be set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_long" c:identifier="g_value_set_long"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_LONG #GValue to @v_long.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_LONG</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_long" transfer-ownership="none"> + <doc xml:space="preserve">long integer value to be set</doc> + <type name="glong" c:type="glong"/> + </parameter> + </parameters> + </method> + <method name="set_object" c:identifier="g_value_set_object"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of %G_TYPE_OBJECT derived type</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">object value to be set</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="set_object_take_ownership" c:identifier="g_value_set_object_take_ownership" introspectable="0" deprecated="1" deprecated-version="2.4"> + <doc xml:space="preserve">This is an internal function introduced mainly for C marshallers.</doc> + <doc-deprecated xml:space="preserve">Use g_value_take_object() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of %G_TYPE_OBJECT derived type</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">object value to be set</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="set_param" c:identifier="g_value_set_param"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_PARAM #GValue to @param.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_PARAM</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="param" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the #GParamSpec to be set</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </method> + <method name="set_param_take_ownership" c:identifier="g_value_set_param_take_ownership" introspectable="0" deprecated="1" deprecated-version="2.4"> + <doc xml:space="preserve">This is an internal function introduced mainly for C marshallers.</doc> + <doc-deprecated xml:space="preserve">Use g_value_take_param() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_PARAM</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="param" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the #GParamSpec to be set</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </method> + <method name="set_pointer" c:identifier="g_value_set_pointer"> + <doc xml:space="preserve">Set the contents of a pointer #GValue to @v_pointer.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of %G_TYPE_POINTER</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_pointer" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">pointer value to be set</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="set_schar" c:identifier="g_value_set_schar" version="2.32"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_CHAR #GValue to @v_char.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_CHAR</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_char" transfer-ownership="none"> + <doc xml:space="preserve">signed 8 bit integer to be set</doc> + <type name="gint8" c:type="gint8"/> + </parameter> + </parameters> + </method> + <method name="set_static_boxed" c:identifier="g_value_set_static_boxed"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of %G_TYPE_BOXED derived type</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_boxed" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">static boxed value to be set</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="set_static_string" c:identifier="g_value_set_static_string"> + <doc xml:space="preserve">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. + +If the the string is a canonical string, using g_value_set_interned_string() +is more appropriate.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_STRING</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">static string to be set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_string" c:identifier="g_value_set_string"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_STRING #GValue to @v_string.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_STRING</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">caller-owned string to be duplicated for the #GValue</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_string_take_ownership" c:identifier="g_value_set_string_take_ownership" deprecated="1" deprecated-version="2.4"> + <doc xml:space="preserve">This is an internal function introduced mainly for C marshallers.</doc> + <doc-deprecated xml:space="preserve">Use g_value_take_string() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_STRING</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">duplicated unowned string to be set</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_uchar" c:identifier="g_value_set_uchar"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_UCHAR</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_uchar" transfer-ownership="none"> + <doc xml:space="preserve">unsigned character value to be set</doc> + <type name="guint8" c:type="guchar"/> + </parameter> + </parameters> + </method> + <method name="set_uint" c:identifier="g_value_set_uint"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_UINT #GValue to @v_uint.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_UINT</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_uint" transfer-ownership="none"> + <doc xml:space="preserve">unsigned integer value to be set</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="set_uint64" c:identifier="g_value_set_uint64"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_UINT64</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_uint64" transfer-ownership="none"> + <doc xml:space="preserve">unsigned 64bit integer value to be set</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + </parameters> + </method> + <method name="set_ulong" c:identifier="g_value_set_ulong"> + <doc xml:space="preserve">Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_ULONG</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_ulong" transfer-ownership="none"> + <doc xml:space="preserve">unsigned long integer value to be set</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + </parameters> + </method> + <method name="set_variant" c:identifier="g_value_set_variant" version="2.26"> + <doc xml:space="preserve">Set the contents of a variant #GValue to @variant. +If the variant is floating, it is consumed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_VARIANT</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="variant" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant, or %NULL</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="take_boxed" c:identifier="g_value_take_boxed" version="2.4"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of %G_TYPE_BOXED derived type</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_boxed" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">duplicated unowned boxed value to be set</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="take_object" c:identifier="g_value_take_object" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of %G_TYPE_OBJECT derived type</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">object value to be set</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="take_param" c:identifier="g_value_take_param" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_PARAM</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="param" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the #GParamSpec to be set</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </method> + <method name="take_string" c:identifier="g_value_take_string" version="2.4"> + <doc xml:space="preserve">Sets the contents of a %G_TYPE_STRING #GValue to @v_string.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_STRING</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="v_string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">string to take ownership of</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </method> + <method name="take_variant" c:identifier="g_value_take_variant" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GValue of type %G_TYPE_VARIANT</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + <parameter name="variant" transfer-ownership="full" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant, or %NULL</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="transform" c:identifier="g_value_transform"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Whether a transformation rule was found and could be applied. + Upon failing transformations, @dest_value is left untouched.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="src_value" transfer-ownership="none"> + <doc xml:space="preserve">Source value.</doc> + <type name="Value" c:type="const GValue*"/> + </instance-parameter> + <parameter name="dest_value" transfer-ownership="none"> + <doc xml:space="preserve">Target value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </method> + <method name="unset" c:identifier="g_value_unset"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">An initialized #GValue structure.</doc> + <type name="Value" c:type="GValue*"/> + </instance-parameter> + </parameters> + </method> + <function name="register_transform_func" c:identifier="g_value_register_transform_func" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="src_type" transfer-ownership="none"> + <doc xml:space="preserve">Source type.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="dest_type" transfer-ownership="none"> + <doc xml:space="preserve">Target type.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="transform_func" transfer-ownership="none"> + <doc xml:space="preserve">a function which transforms values of type @src_type + into value of type @dest_type</doc> + <type name="ValueTransform" c:type="GValueTransform"/> + </parameter> + </parameters> + </function> + <function name="type_compatible" c:identifier="g_value_type_compatible"> + <doc xml:space="preserve">Returns whether a #GValue of type @src_type can be copied into +a #GValue of type @dest_type.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if g_value_copy() is possible with @src_type and @dest_type.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="src_type" transfer-ownership="none"> + <doc xml:space="preserve">source type to be copied.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="dest_type" transfer-ownership="none"> + <doc xml:space="preserve">destination type for copying.</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_transformable" c:identifier="g_value_type_transformable"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the transformation is possible, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="src_type" transfer-ownership="none"> + <doc xml:space="preserve">Source type.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="dest_type" transfer-ownership="none"> + <doc xml:space="preserve">Target type.</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + </record> + <record name="ValueArray" c:type="GValueArray" glib:type-name="GValueArray" glib:get-type="g_value_array_get_type" c:symbol-prefix="value_array"> + <doc xml:space="preserve">A #GValueArray contains an array of #GValue elements.</doc> + <field name="n_values" writable="1"> + <doc xml:space="preserve">number of values contained in the array</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="values" writable="1"> + <doc xml:space="preserve">array of values</doc> + <type name="Value" c:type="GValue*"/> + </field> + <field name="n_prealloced" readable="0" private="1"> + <type name="guint" c:type="guint"/> + </field> + <constructor name="new" c:identifier="g_value_array_new" deprecated="1" deprecated-version="2.32"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use #GArray and g_array_sized_new() instead.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated #GValueArray with 0 values</doc> + <type name="ValueArray" c:type="GValueArray*"/> + </return-value> + <parameters> + <parameter name="n_prealloced" transfer-ownership="none"> + <doc xml:space="preserve">number of values to preallocate space for</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </constructor> + <method name="append" c:identifier="g_value_array_append" deprecated="1" deprecated-version="2.32"> + <doc xml:space="preserve">Insert a copy of @value as last element of @value_array. If @value is +%NULL, an uninitialized value is appended.</doc> + <doc-deprecated xml:space="preserve">Use #GArray and g_array_append_val() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GValueArray passed in as @value_array</doc> + <type name="ValueArray" c:type="GValueArray*"/> + </return-value> + <parameters> + <instance-parameter name="value_array" transfer-ownership="none"> + <doc xml:space="preserve">#GValueArray to add an element to</doc> + <type name="ValueArray" c:type="GValueArray*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">#GValue to copy into #GValueArray, or %NULL</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + </parameters> + </method> + <method name="copy" c:identifier="g_value_array_copy" deprecated="1" deprecated-version="2.32"> + <doc xml:space="preserve">Construct an exact copy of a #GValueArray by duplicating all its +contents.</doc> + <doc-deprecated xml:space="preserve">Use #GArray and g_array_ref() instead.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">Newly allocated copy of #GValueArray</doc> + <type name="ValueArray" c:type="GValueArray*"/> + </return-value> + <parameters> + <instance-parameter name="value_array" transfer-ownership="none"> + <doc xml:space="preserve">#GValueArray to copy</doc> + <type name="ValueArray" c:type="const GValueArray*"/> + </instance-parameter> + </parameters> + </method> + <method name="free" c:identifier="g_value_array_free" introspectable="0" deprecated="1" deprecated-version="2.32"> + <doc xml:space="preserve">Free a #GValueArray including its contents.</doc> + <doc-deprecated xml:space="preserve">Use #GArray and g_array_unref() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="value_array" transfer-ownership="none"> + <doc xml:space="preserve">#GValueArray to free</doc> + <type name="ValueArray" c:type="GValueArray*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_nth" c:identifier="g_value_array_get_nth" deprecated="1" deprecated-version="2.32"> + <doc xml:space="preserve">Return a pointer to the value at @index_ containd in @value_array.</doc> + <doc-deprecated xml:space="preserve">Use g_array_index() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">pointer to a value at @index_ in @value_array</doc> + <type name="Value" c:type="GValue*"/> + </return-value> + <parameters> + <instance-parameter name="value_array" transfer-ownership="none"> + <doc xml:space="preserve">#GValueArray to get a value from</doc> + <type name="ValueArray" c:type="GValueArray*"/> + </instance-parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">index of the value of interest</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="insert" c:identifier="g_value_array_insert" deprecated="1" deprecated-version="2.32"> + <doc xml:space="preserve">Insert a copy of @value at specified position into @value_array. If @value +is %NULL, an uninitialized value is inserted.</doc> + <doc-deprecated xml:space="preserve">Use #GArray and g_array_insert_val() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GValueArray passed in as @value_array</doc> + <type name="ValueArray" c:type="GValueArray*"/> + </return-value> + <parameters> + <instance-parameter name="value_array" transfer-ownership="none"> + <doc xml:space="preserve">#GValueArray to add an element to</doc> + <type name="ValueArray" c:type="GValueArray*"/> + </instance-parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">insertion position, must be <= value_array->;n_values</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">#GValue to copy into #GValueArray, or %NULL</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + </parameters> + </method> + <method name="prepend" c:identifier="g_value_array_prepend" deprecated="1" deprecated-version="2.32"> + <doc xml:space="preserve">Insert a copy of @value as first element of @value_array. If @value is +%NULL, an uninitialized value is prepended.</doc> + <doc-deprecated xml:space="preserve">Use #GArray and g_array_prepend_val() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GValueArray passed in as @value_array</doc> + <type name="ValueArray" c:type="GValueArray*"/> + </return-value> + <parameters> + <instance-parameter name="value_array" transfer-ownership="none"> + <doc xml:space="preserve">#GValueArray to add an element to</doc> + <type name="ValueArray" c:type="GValueArray*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">#GValue to copy into #GValueArray, or %NULL</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + </parameters> + </method> + <method name="remove" c:identifier="g_value_array_remove" deprecated="1" deprecated-version="2.32"> + <doc xml:space="preserve">Remove the value at position @index_ from @value_array.</doc> + <doc-deprecated xml:space="preserve">Use #GArray and g_array_remove_index() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GValueArray passed in as @value_array</doc> + <type name="ValueArray" c:type="GValueArray*"/> + </return-value> + <parameters> + <instance-parameter name="value_array" transfer-ownership="none"> + <doc xml:space="preserve">#GValueArray to remove an element from</doc> + <type name="ValueArray" c:type="GValueArray*"/> + </instance-parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">position of value to remove, which must be less than + @value_array->n_values</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="sort" c:identifier="g_value_array_sort" shadowed-by="sort_with_data" deprecated="1" deprecated-version="2.32"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use #GArray and g_array_sort().</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GValueArray passed in as @value_array</doc> + <type name="ValueArray" c:type="GValueArray*"/> + </return-value> + <parameters> + <instance-parameter name="value_array" transfer-ownership="none"> + <doc xml:space="preserve">#GValueArray to sort</doc> + <type name="ValueArray" c:type="GValueArray*"/> + </instance-parameter> + <parameter name="compare_func" transfer-ownership="none" scope="call"> + <doc xml:space="preserve">function to compare elements</doc> + <type name="GLib.CompareFunc" c:type="GCompareFunc"/> + </parameter> + </parameters> + </method> + <method name="sort_with_data" c:identifier="g_value_array_sort_with_data" shadows="sort" deprecated="1" deprecated-version="2.32"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use #GArray and g_array_sort_with_data().</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GValueArray passed in as @value_array</doc> + <type name="ValueArray" c:type="GValueArray*"/> + </return-value> + <parameters> + <instance-parameter name="value_array" transfer-ownership="none"> + <doc xml:space="preserve">#GValueArray to sort</doc> + <type name="ValueArray" c:type="GValueArray*"/> + </instance-parameter> + <parameter name="compare_func" transfer-ownership="none" scope="call" closure="1"> + <doc xml:space="preserve">function to compare elements</doc> + <type name="GLib.CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">extra data argument provided for @compare_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + </record> + <callback name="ValueTransform" c:type="GValueTransform"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="src_value" transfer-ownership="none"> + <doc xml:space="preserve">Source value.</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="dest_value" transfer-ownership="none"> + <doc xml:space="preserve">Target value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </callback> + <callback name="WeakNotify" c:type="GWeakNotify"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data that was provided when the weak reference was established</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="where_the_object_was" transfer-ownership="none"> + <doc xml:space="preserve">the object being finalized</doc> + <type name="Object" c:type="GObject*"/> + </parameter> + </parameters> + </callback> + <record name="WeakRef" c:type="GWeakRef"> + <doc xml:space="preserve">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.</doc> + <union name="priv" c:type="priv"> + <field name="p" writable="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + </union> + <method name="clear" c:identifier="g_weak_ref_clear" version="2.32" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="weak_ref" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">location of a weak reference, which + may be empty</doc> + <type name="WeakRef" c:type="GWeakRef*"/> + </instance-parameter> + </parameters> + </method> + <method name="get" c:identifier="g_weak_ref_get" version="2.32" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the object pointed to + by @weak_ref, or %NULL if it was empty</doc> + <type name="Object" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="weak_ref" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">location of a weak reference to a #GObject</doc> + <type name="WeakRef" c:type="GWeakRef*"/> + </instance-parameter> + </parameters> + </method> + <method name="init" c:identifier="g_weak_ref_init" version="2.32" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="weak_ref" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">uninitialized or empty location for a weak + reference</doc> + <type name="WeakRef" c:type="GWeakRef*"/> + </instance-parameter> + <parameter name="object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GObject or %NULL</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="set" c:identifier="g_weak_ref_set" version="2.32" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="weak_ref" transfer-ownership="none"> + <doc xml:space="preserve">location for a weak reference</doc> + <type name="WeakRef" c:type="GWeakRef*"/> + </instance-parameter> + <parameter name="object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GObject or %NULL</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + </parameters> + </method> + </record> + <union name="_Value__data__union"> + <field name="v_int" writable="1"> + <type name="gint" c:type="gint"/> + </field> + <field name="v_uint" writable="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="v_long" writable="1"> + <type name="glong" c:type="glong"/> + </field> + <field name="v_ulong" writable="1"> + <type name="gulong" c:type="gulong"/> + </field> + <field name="v_int64" writable="1"> + <type name="gint64" c:type="gint64"/> + </field> + <field name="v_uint64" writable="1"> + <type name="guint64" c:type="guint64"/> + </field> + <field name="v_float" writable="1"> + <type name="gfloat" c:type="gfloat"/> + </field> + <field name="v_double" writable="1"> + <type name="gdouble" c:type="gdouble"/> + </field> + <field name="v_pointer" writable="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + </union> + <function-macro name="assert_finalize_object" c:identifier="g_assert_finalize_object" version="2.62" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="object"> + <doc xml:space="preserve">an object</doc> + </parameter> + </parameters> + </function-macro> + <function name="boxed_copy" c:identifier="g_boxed_copy"> + <doc xml:space="preserve">Provide a copy of a boxed structure @src_boxed which is of type @boxed_type.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">The newly created copy of the boxed + structure.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="boxed_type" transfer-ownership="none"> + <doc xml:space="preserve">The type of @src_boxed.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="src_boxed" transfer-ownership="none"> + <doc xml:space="preserve">The boxed structure to be copied.</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="boxed_free" c:identifier="g_boxed_free"> + <doc xml:space="preserve">Free the boxed structure @boxed which is of type @boxed_type.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="boxed_type" transfer-ownership="none"> + <doc xml:space="preserve">The type of @boxed.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="boxed" transfer-ownership="none"> + <doc xml:space="preserve">The boxed structure to be freed.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="boxed_type_register_static" c:identifier="g_boxed_type_register_static" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">New %G_TYPE_BOXED derived type id for @name.</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">Name of the new boxed type.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="boxed_copy" transfer-ownership="none"> + <doc xml:space="preserve">Boxed structure copy function.</doc> + <type name="BoxedCopyFunc" c:type="GBoxedCopyFunc"/> + </parameter> + <parameter name="boxed_free" transfer-ownership="none"> + <doc xml:space="preserve">Boxed structure free function.</doc> + <type name="BoxedFreeFunc" c:type="GBoxedFreeFunc"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_BOOLEAN__BOXED_BOXED" c:identifier="g_cclosure_marshal_BOOLEAN__BOXED_BOXED" moved-to="CClosure.marshal_BOOLEAN__BOXED_BOXED"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">A #GClosure.</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">The length of the @param_values array.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">An array of #GValues holding the arguments + on which to invoke the callback of closure.</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The invocation hint given as the last argument to + g_closure_invoke().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_BOOLEAN__FLAGS" c:identifier="g_cclosure_marshal_BOOLEAN__FLAGS" moved-to="CClosure.marshal_BOOLEAN__FLAGS"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue which can store the returned #gboolean</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding instance and arg1</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_STRING__OBJECT_POINTER" c:identifier="g_cclosure_marshal_STRING__OBJECT_POINTER" moved-to="CClosure.marshal_STRING__OBJECT_POINTER"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue, which can store the returned string</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">3</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding instance, arg1 and arg2</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__BOOLEAN" c:identifier="g_cclosure_marshal_VOID__BOOLEAN" moved-to="CClosure.marshal_VOID__BOOLEAN"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #gboolean parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__BOXED" c:identifier="g_cclosure_marshal_VOID__BOXED" moved-to="CClosure.marshal_VOID__BOXED"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #GBoxed* parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__CHAR" c:identifier="g_cclosure_marshal_VOID__CHAR" moved-to="CClosure.marshal_VOID__CHAR"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #gchar parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__DOUBLE" c:identifier="g_cclosure_marshal_VOID__DOUBLE" moved-to="CClosure.marshal_VOID__DOUBLE"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #gdouble parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__ENUM" c:identifier="g_cclosure_marshal_VOID__ENUM" moved-to="CClosure.marshal_VOID__ENUM"> + <doc xml:space="preserve">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..</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the enumeration parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__FLAGS" c:identifier="g_cclosure_marshal_VOID__FLAGS" moved-to="CClosure.marshal_VOID__FLAGS"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the flags parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__FLOAT" c:identifier="g_cclosure_marshal_VOID__FLOAT" moved-to="CClosure.marshal_VOID__FLOAT"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #gfloat parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__INT" c:identifier="g_cclosure_marshal_VOID__INT" moved-to="CClosure.marshal_VOID__INT"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gint arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #gint parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__LONG" c:identifier="g_cclosure_marshal_VOID__LONG" moved-to="CClosure.marshal_VOID__LONG"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, glong arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #glong parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__OBJECT" c:identifier="g_cclosure_marshal_VOID__OBJECT" moved-to="CClosure.marshal_VOID__OBJECT"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #GObject* parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__PARAM" c:identifier="g_cclosure_marshal_VOID__PARAM" moved-to="CClosure.marshal_VOID__PARAM"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #GParamSpec* parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__POINTER" c:identifier="g_cclosure_marshal_VOID__POINTER" moved-to="CClosure.marshal_VOID__POINTER"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #gpointer parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__STRING" c:identifier="g_cclosure_marshal_VOID__STRING" moved-to="CClosure.marshal_VOID__STRING"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #gchar* parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__UCHAR" c:identifier="g_cclosure_marshal_VOID__UCHAR" moved-to="CClosure.marshal_VOID__UCHAR"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #guchar parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__UINT" c:identifier="g_cclosure_marshal_VOID__UINT" moved-to="CClosure.marshal_VOID__UINT"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guint arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #guint parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__UINT_POINTER" c:identifier="g_cclosure_marshal_VOID__UINT_POINTER" moved-to="CClosure.marshal_VOID__UINT_POINTER"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">3</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding instance, arg1 and arg2</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__ULONG" c:identifier="g_cclosure_marshal_VOID__ULONG" moved-to="CClosure.marshal_VOID__ULONG"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #gulong parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__VARIANT" c:identifier="g_cclosure_marshal_VOID__VARIANT" moved-to="CClosure.marshal_VOID__VARIANT" version="2.26"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">2</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding the instance and the #GVariant* parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_VOID__VOID" c:identifier="g_cclosure_marshal_VOID__VOID" moved-to="CClosure.marshal_VOID__VOID"> + <doc xml:space="preserve">A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gpointer user_data)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the #GClosure to which the marshaller belongs</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">ignored</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">1</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue array holding only the instance</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the invocation hint given as the last argument + to g_closure_invoke()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">additional data specified when registering the marshaller</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_marshal_generic" c:identifier="g_cclosure_marshal_generic" moved-to="CClosure.marshal_generic" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">A #GClosure.</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="return_gvalue" transfer-ownership="none"> + <doc xml:space="preserve">A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="n_param_values" transfer-ownership="none"> + <doc xml:space="preserve">The length of the @param_values array.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_values" transfer-ownership="none"> + <doc xml:space="preserve">An array of #GValues holding the arguments + on which to invoke the callback of closure.</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="invocation_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The invocation hint given as the last argument to + g_closure_invoke().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="cclosure_new" c:identifier="g_cclosure_new" moved-to="CClosure.new" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new #GCClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </return-value> + <parameters> + <parameter name="callback_func" transfer-ownership="none" nullable="1" allow-none="1" closure="1"> + <doc xml:space="preserve">the function to invoke</doc> + <type name="Callback" c:type="GCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="0"> + <doc xml:space="preserve">user data to pass to @callback_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy_data" transfer-ownership="none"> + <doc xml:space="preserve">destroy notify to be called when @user_data is no longer used</doc> + <type name="ClosureNotify" c:type="GClosureNotify"/> + </parameter> + </parameters> + </function> + <function name="cclosure_new_object" c:identifier="g_cclosure_new_object" moved-to="CClosure.new_object" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GCClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </return-value> + <parameters> + <parameter name="callback_func" transfer-ownership="none"> + <doc xml:space="preserve">the function to invoke</doc> + <type name="Callback" c:type="GCallback"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject pointer to pass to @callback_func</doc> + <type name="Object" c:type="GObject*"/> + </parameter> + </parameters> + </function> + <function name="cclosure_new_object_swap" c:identifier="g_cclosure_new_object_swap" moved-to="CClosure.new_object_swap" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GCClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </return-value> + <parameters> + <parameter name="callback_func" transfer-ownership="none"> + <doc xml:space="preserve">the function to invoke</doc> + <type name="Callback" c:type="GCallback"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject pointer to pass to @callback_func</doc> + <type name="Object" c:type="GObject*"/> + </parameter> + </parameters> + </function> + <function name="cclosure_new_swap" c:identifier="g_cclosure_new_swap" moved-to="CClosure.new_swap" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new #GCClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </return-value> + <parameters> + <parameter name="callback_func" transfer-ownership="none" nullable="1" allow-none="1" closure="1"> + <doc xml:space="preserve">the function to invoke</doc> + <type name="Callback" c:type="GCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="0"> + <doc xml:space="preserve">user data to pass to @callback_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy_data" transfer-ownership="none"> + <doc xml:space="preserve">destroy notify to be called when @user_data is no longer used</doc> + <type name="ClosureNotify" c:type="GClosureNotify"/> + </parameter> + </parameters> + </function> + <function name="clear_object" c:identifier="g_clear_object" version="2.28" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object_ptr" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GObject reference</doc> + <type name="Object" c:type="GObject**"/> + </parameter> + </parameters> + </function> + <function name="clear_signal_handler" c:identifier="g_clear_signal_handler" version="2.62"> + <doc xml:space="preserve">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. + +There is also a macro version of this function so that the code +will be inlined.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="handler_id_ptr" transfer-ownership="none"> + <doc xml:space="preserve">A pointer to a handler ID (of type #gulong) of the handler to be disconnected.</doc> + <type name="gulong" c:type="gulong*"/> + </parameter> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">The instance to remove the signal handler from. + This pointer may be %NULL or invalid, if the handler ID is zero.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function-macro name="clear_weak_pointer" c:identifier="g_clear_weak_pointer" version="2.56" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="weak_pointer_location"> + <doc xml:space="preserve">The memory address of a pointer</doc> + </parameter> + </parameters> + </function-macro> + <function name="enum_complete_type_info" c:identifier="g_enum_complete_type_info"> + <doc xml:space="preserve">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); +} +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="g_enum_type" transfer-ownership="none"> + <doc xml:space="preserve">the type identifier of the type being completed</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="info" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the #GTypeInfo struct to be filled in</doc> + <type name="TypeInfo" c:type="GTypeInfo*"/> + </parameter> + <parameter name="const_values" transfer-ownership="none"> + <doc xml:space="preserve">An array of #GEnumValue structs for the possible + enumeration values. The array is terminated by a struct with all + members being 0.</doc> + <type name="EnumValue" c:type="const GEnumValue*"/> + </parameter> + </parameters> + </function> + <function name="enum_get_value" c:identifier="g_enum_get_value"> + <doc xml:space="preserve">Returns the #GEnumValue for a value.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the #GEnumValue for @value, or %NULL + if @value is not a member of the enumeration</doc> + <type name="EnumValue" c:type="GEnumValue*"/> + </return-value> + <parameters> + <parameter name="enum_class" transfer-ownership="none"> + <doc xml:space="preserve">a #GEnumClass</doc> + <type name="EnumClass" c:type="GEnumClass*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value to look up</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="enum_get_value_by_name" c:identifier="g_enum_get_value_by_name"> + <doc xml:space="preserve">Looks up a #GEnumValue by name.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the #GEnumValue with name @name, + or %NULL if the enumeration doesn't have a member + with that name</doc> + <type name="EnumValue" c:type="GEnumValue*"/> + </return-value> + <parameters> + <parameter name="enum_class" transfer-ownership="none"> + <doc xml:space="preserve">a #GEnumClass</doc> + <type name="EnumClass" c:type="GEnumClass*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name to look up</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="enum_get_value_by_nick" c:identifier="g_enum_get_value_by_nick"> + <doc xml:space="preserve">Looks up a #GEnumValue by nickname.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the #GEnumValue with nickname @nick, + or %NULL if the enumeration doesn't have a member + with that nickname</doc> + <type name="EnumValue" c:type="GEnumValue*"/> + </return-value> + <parameters> + <parameter name="enum_class" transfer-ownership="none"> + <doc xml:space="preserve">a #GEnumClass</doc> + <type name="EnumClass" c:type="GEnumClass*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">the nickname to look up</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="enum_register_static" c:identifier="g_enum_register_static"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The new type identifier.</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">A nul-terminated string used as the name of the new type.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="const_static_values" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="EnumValue" c:type="const GEnumValue*"/> + </parameter> + </parameters> + </function> + <function name="enum_to_string" c:identifier="g_enum_to_string" version="2.54"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated text string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="g_enum_type" transfer-ownership="none"> + <doc xml:space="preserve">the type identifier of a #GEnumClass type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <docsection name="enumerations_flags"> + <doc xml:space="preserve">The GLib type system provides fundamental types for enumeration and +flags types. (Flags types are like enumerations, but allow their +values to be combined by bitwise or). A registered enumeration or +flags type associates a name and a nickname with each allowed +value, and the methods g_enum_get_value_by_name(), +g_enum_get_value_by_nick(), g_flags_get_value_by_name() and +g_flags_get_value_by_nick() can look up values by their name or +nickname. When an enumeration or flags type is registered with the +GLib type system, it can be used as value type for object +properties, using g_param_spec_enum() or g_param_spec_flags(). + +GObject ships with a utility called [glib-mkenums][glib-mkenums], +that can construct suitable type registration functions from C enumeration +definitions. + +Example of how to get a string representation of an enum value: +|[<!-- language="C" --> +GEnumClass *enum_class; +GEnumValue *enum_value; + +enum_class = g_type_class_ref (MAMAN_TYPE_MY_ENUM); +enum_value = g_enum_get_value (enum_class, MAMAN_MY_ENUM_FOO); + +g_print ("Name: %s\n", enum_value->value_name); + +g_type_class_unref (enum_class); +]|</doc> + </docsection> + <function name="flags_complete_type_info" c:identifier="g_flags_complete_type_info"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="g_flags_type" transfer-ownership="none"> + <doc xml:space="preserve">the type identifier of the type being completed</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="info" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the #GTypeInfo struct to be filled in</doc> + <type name="TypeInfo" c:type="GTypeInfo*"/> + </parameter> + <parameter name="const_values" transfer-ownership="none"> + <doc xml:space="preserve">An array of #GFlagsValue structs for the possible + enumeration values. The array is terminated by a struct with all + members being 0.</doc> + <type name="FlagsValue" c:type="const GFlagsValue*"/> + </parameter> + </parameters> + </function> + <function name="flags_get_first_value" c:identifier="g_flags_get_first_value"> + <doc xml:space="preserve">Returns the first #GFlagsValue which is set in @value.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the first #GFlagsValue which is set in + @value, or %NULL if none is set</doc> + <type name="FlagsValue" c:type="GFlagsValue*"/> + </return-value> + <parameters> + <parameter name="flags_class" transfer-ownership="none"> + <doc xml:space="preserve">a #GFlagsClass</doc> + <type name="FlagsClass" c:type="GFlagsClass*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="flags_get_value_by_name" c:identifier="g_flags_get_value_by_name"> + <doc xml:space="preserve">Looks up a #GFlagsValue by name.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the #GFlagsValue with name @name, + or %NULL if there is no flag with that name</doc> + <type name="FlagsValue" c:type="GFlagsValue*"/> + </return-value> + <parameters> + <parameter name="flags_class" transfer-ownership="none"> + <doc xml:space="preserve">a #GFlagsClass</doc> + <type name="FlagsClass" c:type="GFlagsClass*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name to look up</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="flags_get_value_by_nick" c:identifier="g_flags_get_value_by_nick"> + <doc xml:space="preserve">Looks up a #GFlagsValue by nickname.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the #GFlagsValue with nickname @nick, + or %NULL if there is no flag with that nickname</doc> + <type name="FlagsValue" c:type="GFlagsValue*"/> + </return-value> + <parameters> + <parameter name="flags_class" transfer-ownership="none"> + <doc xml:space="preserve">a #GFlagsClass</doc> + <type name="FlagsClass" c:type="GFlagsClass*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">the nickname to look up</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="flags_register_static" c:identifier="g_flags_register_static"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The new type identifier.</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">A nul-terminated string used as the name of the new type.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="const_static_values" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="FlagsValue" c:type="const GFlagsValue*"/> + </parameter> + </parameters> + </function> + <function name="flags_to_string" c:identifier="g_flags_to_string" version="2.54"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated text string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="flags_type" transfer-ownership="none"> + <doc xml:space="preserve">the type identifier of a #GFlagsClass type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <docsection name="gboxed"> + <doc xml:space="preserve">#GBoxed is a generic wrapper mechanism for arbitrary C structures. The only +thing the type system needs to know about the structures is how to copy them +(a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc) — beyond that +they are treated as opaque chunks of memory. + +Boxed types are useful for simple value-holder structures like rectangles or +points. They can also be used for wrapping structures defined in non-#GObject +based libraries. They allow arbitrary structures to be handled in a uniform +way, allowing uniform copying (or referencing) and freeing (or unreferencing) +of them, and uniform representation of the type of the contained structure. +In turn, this allows any type which can be boxed to be set as the data in a +#GValue, which allows for polymorphic handling of a much wider range of data +types, and hence usage of such types as #GObject property values. + +#GBoxed is designed so that reference counted types can be boxed. Use the +type’s ‘ref’ function as the #GBoxedCopyFunc, and its ‘unref’ function as the +#GBoxedFreeFunc. For example, for #GBytes, the #GBoxedCopyFunc is +g_bytes_ref(), and the #GBoxedFreeFunc is g_bytes_unref().</doc> + </docsection> + <docsection name="generic_values"> + <doc xml:space="preserve">The #GValue structure is basically a variable container that consists +of a type identifier and a specific value of that type. +The type identifier within a #GValue structure always determines the +type of the associated value. +To create an undefined #GValue structure, simply create a zero-filled +#GValue structure. To initialize the #GValue, use the g_value_init() +function. A #GValue cannot be used until it is initialized. +The basic type operations (such as freeing and copying) are determined +by the #GTypeValueTable associated with the type ID stored in the #GValue. +Other #GValue operations (such as converting values between types) are +provided by this interface. + +The code in the example program below demonstrates #GValue's +features. + +|[<!-- language="C" --> +#include <glib-object.h> + +static void +int2string (const GValue *src_value, + GValue *dest_value) +{ + if (g_value_get_int (src_value) == 42) + g_value_set_static_string (dest_value, "An important number"); + else + g_value_set_static_string (dest_value, "What's that?"); +} + +int +main (int argc, + char *argv[]) +{ + // GValues must be initialized + GValue a = G_VALUE_INIT; + GValue b = G_VALUE_INIT; + const gchar *message; + + // The GValue starts empty + g_assert (!G_VALUE_HOLDS_STRING (&a)); + + // Put a string in it + g_value_init (&a, G_TYPE_STRING); + g_assert (G_VALUE_HOLDS_STRING (&a)); + g_value_set_static_string (&a, "Hello, world!"); + g_printf ("%s\n", g_value_get_string (&a)); + + // Reset it to its pristine state + g_value_unset (&a); + + // It can then be reused for another type + g_value_init (&a, G_TYPE_INT); + g_value_set_int (&a, 42); + + // Attempt to transform it into a GValue of type STRING + g_value_init (&b, G_TYPE_STRING); + + // An INT is transformable to a STRING + g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING)); + + g_value_transform (&a, &b); + g_printf ("%s\n", g_value_get_string (&b)); + + // Attempt to transform it again using a custom transform function + g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string); + g_value_transform (&a, &b); + g_printf ("%s\n", g_value_get_string (&b)); + return 0; +} +]|</doc> + </docsection> + <docsection name="gtype"> + <doc xml:space="preserve">The GType API is the foundation of the GObject system. It provides the +facilities for registering and managing all fundamental data types, +user-defined object and interface types. + +For type creation and registration purposes, all types fall into one of +two categories: static or dynamic. Static types are never loaded or +unloaded at run-time as dynamic types may be. Static types are created +with g_type_register_static() that gets type specific information passed +in via a #GTypeInfo structure. + +Dynamic types are created with g_type_register_dynamic() which takes a +#GTypePlugin structure instead. The remaining type information (the +#GTypeInfo structure) is retrieved during runtime through #GTypePlugin +and the g_type_plugin_*() API. + +These registration functions are usually called only once from a +function whose only purpose is to return the type identifier for a +specific class. Once the type (or class or interface) is registered, +it may be instantiated, inherited, or implemented depending on exactly +what sort of type it is. + +There is also a third registration function for registering fundamental +types called g_type_register_fundamental() which requires both a #GTypeInfo +structure and a #GTypeFundamentalInfo structure but it is seldom used +since most fundamental types are predefined rather than user-defined. + +Type instance and class structs are limited to a total of 64 KiB, +including all parent types. Similarly, type instances' private data +(as created by G_ADD_PRIVATE()) are limited to a total of +64 KiB. If a type instance needs a large static buffer, allocate it +separately (typically by using #GArray or #GPtrArray) and put a pointer +to the buffer in the structure. + +As mentioned in the [GType conventions][gtype-conventions], type names must +be at least three characters long. There is no upper length limit. The first +character must be a letter (a–z or A–Z) or an underscore (‘_’). Subsequent +characters can be letters, numbers or any of ‘-_+’.</doc> + </docsection> + <function name="gtype_get_type" c:identifier="g_gtype_get_type"> + <return-value transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </return-value> + </function> + <docsection name="objects"> + <doc xml:space="preserve">GObject is the fundamental type providing the common attributes and +methods for all object types in GTK+, Pango and other libraries +based on GObject. The GObject class provides methods for object +construction and destruction, property access methods, and signal +support. Signals are described in detail [here][gobject-Signals]. + +For a tutorial on implementing a new GObject class, see [How to define and +implement a new GObject][howto-gobject]. For a list of naming conventions for +GObjects and their methods, see the [GType conventions][gtype-conventions]. +For the high-level concepts behind GObject, read [Instantiatable classed types: +Objects][gtype-instantiatable-classed]. + +## Floating references # {#floating-ref} + +**Note**: Floating references are a C convenience API and should not be +used in modern GObject code. Language bindings in particular find the +concept highly problematic, as floating references are not identifiable +through annotations, and neither are deviations from the floating reference +behavior, like types that inherit from #GInitiallyUnowned and still return +a full reference from g_object_new(). + +GInitiallyUnowned is derived from GObject. The only difference between +the two is that the initial reference of a GInitiallyUnowned is flagged +as a "floating" reference. This means that it is not specifically +claimed to be "owned" by any code portion. The main motivation for +providing floating references is C convenience. In particular, it +allows code to be written as: +|[<!-- language="C" --> +container = create_container (); +container_add_child (container, create_child()); +]| +If container_add_child() calls g_object_ref_sink() on the passed-in child, +no reference of the newly created child is leaked. Without floating +references, container_add_child() can only g_object_ref() the new child, +so to implement this code without reference leaks, it would have to be +written as: +|[<!-- language="C" --> +Child *child; +container = create_container (); +child = create_child (); +container_add_child (container, child); +g_object_unref (child); +]| +The floating reference can be converted into an ordinary reference by +calling g_object_ref_sink(). For already sunken objects (objects that +don't have a floating reference anymore), g_object_ref_sink() is equivalent +to g_object_ref() and returns a new reference. + +Since floating references are useful almost exclusively for C convenience, +language bindings that provide automated reference and memory ownership +maintenance (such as smart pointers or garbage collection) should not +expose floating references in their API. The best practice for handling +types that have initially floating references is to immediately sink those +references after g_object_new() returns, by checking if the #GType +inherits from #GInitiallyUnowned. For instance: + +|[<!-- language="C" --> +GObject *res = g_object_new_with_properties (gtype, + n_props, + prop_names, + prop_values); + +// or: if (g_type_is_a (gtype, G_TYPE_INITIALLY_UNOWNED)) +if (G_IS_INITIALLY_UNOWNED (res)) + g_object_ref_sink (res); + +return res; +]| + +Some object implementations may need to save an objects floating state +across certain code portions (an example is #GtkMenu), to achieve this, +the following sequence can be used: + +|[<!-- language="C" --> +// save floating state +gboolean was_floating = g_object_is_floating (object); +g_object_ref_sink (object); +// protected code portion + +... + +// restore floating state +if (was_floating) + g_object_force_floating (object); +else + g_object_unref (object); // release previously acquired reference +]|</doc> + </docsection> + <function name="param_spec_boolean" c:identifier="g_param_spec_boolean"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_boxed" c:identifier="g_param_spec_boxed"> + <doc xml:space="preserve">Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED +derived property. + +See g_param_spec_internal() for details on property names.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="boxed_type" transfer-ownership="none"> + <doc xml:space="preserve">%G_TYPE_BOXED derived type of this property</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_char" c:identifier="g_param_spec_char"> + <doc xml:space="preserve">Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="minimum" transfer-ownership="none"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="gint8" c:type="gint8"/> + </parameter> + <parameter name="maximum" transfer-ownership="none"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="gint8" c:type="gint8"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gint8" c:type="gint8"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_double" c:identifier="g_param_spec_double"> + <doc xml:space="preserve">Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE +property. + +See g_param_spec_internal() for details on property names.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="minimum" transfer-ownership="none"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + <parameter name="maximum" transfer-ownership="none"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_enum" c:identifier="g_param_spec_enum"> + <doc xml:space="preserve">Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM +property. + +See g_param_spec_internal() for details on property names.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="enum_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType derived from %G_TYPE_ENUM</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_flags" c:identifier="g_param_spec_flags"> + <doc xml:space="preserve">Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS +property. + +See g_param_spec_internal() for details on property names.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType derived from %G_TYPE_FLAGS</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_float" c:identifier="g_param_spec_float"> + <doc xml:space="preserve">Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. + +See g_param_spec_internal() for details on property names.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="minimum" transfer-ownership="none"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="gfloat" c:type="gfloat"/> + </parameter> + <parameter name="maximum" transfer-ownership="none"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="gfloat" c:type="gfloat"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gfloat" c:type="gfloat"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_gtype" c:identifier="g_param_spec_gtype" version="2.10"> + <doc xml:space="preserve">Creates a new #GParamSpecGType instance specifying a +%G_TYPE_GTYPE property. + +See g_param_spec_internal() for details on property names.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="is_a_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType whose subtypes are allowed as values + of the property (use %G_TYPE_NONE for any type)</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_int" c:identifier="g_param_spec_int"> + <doc xml:space="preserve">Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. + +See g_param_spec_internal() for details on property names.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="minimum" transfer-ownership="none"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="maximum" transfer-ownership="none"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_int64" c:identifier="g_param_spec_int64"> + <doc xml:space="preserve">Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. + +See g_param_spec_internal() for details on property names.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="minimum" transfer-ownership="none"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="maximum" transfer-ownership="none"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_long" c:identifier="g_param_spec_long"> + <doc xml:space="preserve">Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. + +See g_param_spec_internal() for details on property names.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="minimum" transfer-ownership="none"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="glong" c:type="glong"/> + </parameter> + <parameter name="maximum" transfer-ownership="none"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="glong" c:type="glong"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="glong" c:type="glong"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_object" c:identifier="g_param_spec_object"> + <doc xml:space="preserve">Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT +derived property. + +See g_param_spec_internal() for details on property names.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_type" transfer-ownership="none"> + <doc xml:space="preserve">%G_TYPE_OBJECT derived type of this property</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_override" c:identifier="g_param_spec_override" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">the newly created #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the property.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="overridden" transfer-ownership="none"> + <doc xml:space="preserve">The property that is being overridden</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + </parameters> + </function> + <function name="param_spec_param" c:identifier="g_param_spec_param"> + <doc xml:space="preserve">Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM +property. + +See g_param_spec_internal() for details on property names.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="param_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType derived from %G_TYPE_PARAM</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_pointer" c:identifier="g_param_spec_pointer"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_string" c:identifier="g_param_spec_string"> + <doc xml:space="preserve">Creates a new #GParamSpecString instance. + +See g_param_spec_internal() for details on property names.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="default_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_uchar" c:identifier="g_param_spec_uchar"> + <doc xml:space="preserve">Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="minimum" transfer-ownership="none"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="guint8" c:type="guint8"/> + </parameter> + <parameter name="maximum" transfer-ownership="none"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="guint8" c:type="guint8"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="guint8" c:type="guint8"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_uint" c:identifier="g_param_spec_uint"> + <doc xml:space="preserve">Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. + +See g_param_spec_internal() for details on property names.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="minimum" transfer-ownership="none"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="maximum" transfer-ownership="none"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_uint64" c:identifier="g_param_spec_uint64"> + <doc xml:space="preserve">Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 +property. + +See g_param_spec_internal() for details on property names.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="minimum" transfer-ownership="none"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="maximum" transfer-ownership="none"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_ulong" c:identifier="g_param_spec_ulong"> + <doc xml:space="preserve">Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG +property. + +See g_param_spec_internal() for details on property names.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="minimum" transfer-ownership="none"> + <doc xml:space="preserve">minimum value for the property specified</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + <parameter name="maximum" transfer-ownership="none"> + <doc xml:space="preserve">maximum value for the property specified</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_unichar" c:identifier="g_param_spec_unichar"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <doc xml:space="preserve">default value for the property specified</doc> + <type name="gunichar" c:type="gunichar"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_value_array" c:identifier="g_param_spec_value_array" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">a newly created parameter specification</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="element_spec" transfer-ownership="none"> + <doc xml:space="preserve">a #GParamSpec describing the elements contained in + arrays of this property, may be %NULL</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_spec_variant" c:identifier="g_param_spec_variant" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the newly created #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">canonical name of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="nick" transfer-ownership="none"> + <doc xml:space="preserve">nick name for the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="blurb" transfer-ownership="none"> + <doc xml:space="preserve">description of the property specified</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantType</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="default_value" transfer-ownership="full" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant of type @type to + use as the default value, or %NULL</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the property specified</doc> + <type name="ParamFlags" c:type="GParamFlags"/> + </parameter> + </parameters> + </function> + <function name="param_type_register_static" c:identifier="g_param_type_register_static"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The new type identifier.</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">0-terminated string used as the name of the new #GParamSpec type.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="pspec_info" transfer-ownership="none"> + <doc xml:space="preserve">The #GParamSpecTypeInfo for this #GParamSpec type.</doc> + <type name="ParamSpecTypeInfo" c:type="const GParamSpecTypeInfo*"/> + </parameter> + </parameters> + </function> + <function name="param_value_convert" c:identifier="g_param_value_convert"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if transformation and validation were successful, + %FALSE otherwise and @dest_value is left untouched.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + <parameter name="src_value" transfer-ownership="none"> + <doc xml:space="preserve">source #GValue</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="dest_value" transfer-ownership="none"> + <doc xml:space="preserve">destination #GValue of correct type for @pspec</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="strict_validation" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE requires @dest_value to conform to @pspec +without modifications</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="param_value_defaults" c:identifier="g_param_value_defaults"> + <doc xml:space="preserve">Checks whether @value contains the default value as specified in @pspec.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether @value contains the canonical default for this @pspec</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue of correct type for @pspec</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + </parameters> + </function> + <function name="param_value_set_default" c:identifier="g_param_value_set_default"> + <doc xml:space="preserve">Sets @value to its default value as specified in @pspec.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue of correct type for @pspec; since 2.64, you + can also pass an empty #GValue, initialized with %G_VALUE_INIT</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </function> + <docsection name="param_value_types"> + <doc xml:space="preserve">#GValue provides an abstract container structure which can be +copied, transformed and compared while holding a value of any +(derived) type, which is registered as a #GType with a +#GTypeValueTable in its #GTypeInfo structure. Parameter +specifications for most value types can be created as #GParamSpec +derived instances, to implement e.g. #GObject properties which +operate on #GValue containers. + +Parameter names need to start with a letter (a-z or A-Z). Subsequent +characters can be letters, numbers or a '-'. +All other characters are replaced by a '-' during construction.</doc> + </docsection> + <function name="param_value_validate" c:identifier="g_param_value_validate"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether modifying @value was necessary to ensure validity</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue of correct type for @pspec</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </function> + <function name="param_values_cmp" c:identifier="g_param_values_cmp"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">-1, 0 or +1, for a less than, equal to or greater than result</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="pspec" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GParamSpec</doc> + <type name="ParamSpec" c:type="GParamSpec*"/> + </parameter> + <parameter name="value1" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue of correct type for @pspec</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="value2" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue of correct type for @pspec</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + </parameters> + </function> + <function name="pointer_type_register_static" c:identifier="g_pointer_type_register_static"> + <doc xml:space="preserve">Creates a new %G_TYPE_POINTER derived type id for a new +pointer type with name @name.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a new %G_TYPE_POINTER derived type id for @name.</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the new pointer type.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function-macro name="set_object" c:identifier="g_set_object" version="2.44" introspectable="0"> + <doc xml:space="preserve">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"); + } +]|</doc> + <parameters> + <parameter name="object_ptr"> + <doc xml:space="preserve">a pointer to a #GObject reference</doc> + </parameter> + <parameter name="new_object"> + <doc xml:space="preserve">a pointer to the new #GObject to + assign to it, or %NULL to clear the pointer</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="set_weak_pointer" c:identifier="g_set_weak_pointer" version="2.56" introspectable="0"> + <doc xml:space="preserve">Updates a pointer to weakly refer to @new_object. It assigns @new_object +to @weak_pointer_location and ensures that @weak_pointer_location will +automatically 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"); + } +]|</doc> + <parameters> + <parameter name="weak_pointer_location"> + <doc xml:space="preserve">the memory address of a pointer</doc> + </parameter> + <parameter name="new_object"> + <doc xml:space="preserve">a pointer to the new #GObject to + assign to it, or %NULL to clear the pointer</doc> + </parameter> + </parameters> + </function-macro> + <function name="signal_accumulator_first_wins" c:identifier="g_signal_accumulator_first_wins" version="2.28"> + <doc xml:space="preserve">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").</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">standard #GSignalAccumulator result</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="ihint" transfer-ownership="none"> + <doc xml:space="preserve">standard #GSignalAccumulator parameter</doc> + <type name="SignalInvocationHint" c:type="GSignalInvocationHint*"/> + </parameter> + <parameter name="return_accu" transfer-ownership="none"> + <doc xml:space="preserve">standard #GSignalAccumulator parameter</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="handler_return" transfer-ownership="none"> + <doc xml:space="preserve">standard #GSignalAccumulator parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="dummy" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">standard #GSignalAccumulator parameter</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="signal_accumulator_true_handled" c:identifier="g_signal_accumulator_true_handled" version="2.4"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">standard #GSignalAccumulator result</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="ihint" transfer-ownership="none"> + <doc xml:space="preserve">standard #GSignalAccumulator parameter</doc> + <type name="SignalInvocationHint" c:type="GSignalInvocationHint*"/> + </parameter> + <parameter name="return_accu" transfer-ownership="none"> + <doc xml:space="preserve">standard #GSignalAccumulator parameter</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + <parameter name="handler_return" transfer-ownership="none"> + <doc xml:space="preserve">standard #GSignalAccumulator parameter</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="dummy" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">standard #GSignalAccumulator parameter</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="signal_add_emission_hook" c:identifier="g_signal_add_emission_hook"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the hook id, for later use with g_signal_remove_emission_hook().</doc> + <type name="gulong" c:type="gulong"/> + </return-value> + <parameters> + <parameter name="signal_id" transfer-ownership="none"> + <doc xml:space="preserve">the signal identifier, as returned by g_signal_lookup().</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="detail" transfer-ownership="none"> + <doc xml:space="preserve">the detail on which to call the hook.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="hook_func" transfer-ownership="none" scope="notified" closure="3" destroy="4"> + <doc xml:space="preserve">a #GSignalEmissionHook function.</doc> + <type name="SignalEmissionHook" c:type="GSignalEmissionHook"/> + </parameter> + <parameter name="hook_data" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="2"> + <doc xml:space="preserve">user data for @hook_func.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="data_destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async" destroy="3"> + <doc xml:space="preserve">a #GDestroyNotify for @hook_data.</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="signal_chain_from_overridden" c:identifier="g_signal_chain_from_overridden"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="instance_and_params" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <array zero-terminated="0" c:type="const GValue*"> + <type name="Value" c:type="GValue"/> + </array> + </parameter> + <parameter name="return_value" transfer-ownership="none"> + <doc xml:space="preserve">Location for the return value.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </function> + <function name="signal_chain_from_overridden_handler" c:identifier="g_signal_chain_from_overridden_handler" version="2.18" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance the signal is being + emitted on.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function-macro name="signal_connect" c:identifier="g_signal_connect" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <parameters> + <parameter name="instance"> + <doc xml:space="preserve">the instance to connect to.</doc> + </parameter> + <parameter name="detailed_signal"> + <doc xml:space="preserve">a string of the form "signal-name::detail".</doc> + </parameter> + <parameter name="c_handler"> + <doc xml:space="preserve">the #GCallback to connect.</doc> + </parameter> + <parameter name="data"> + <doc xml:space="preserve">data to pass to @c_handler calls.</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="signal_connect_after" c:identifier="g_signal_connect_after" introspectable="0"> + <doc xml:space="preserve">Connects a #GCallback function to a signal for a particular object. + +The handler will be called after the default handler of the signal.</doc> + <parameters> + <parameter name="instance"> + <doc xml:space="preserve">the instance to connect to.</doc> + </parameter> + <parameter name="detailed_signal"> + <doc xml:space="preserve">a string of the form "signal-name::detail".</doc> + </parameter> + <parameter name="c_handler"> + <doc xml:space="preserve">the #GCallback to connect.</doc> + </parameter> + <parameter name="data"> + <doc xml:space="preserve">data to pass to @c_handler calls.</doc> + </parameter> + </parameters> + </function-macro> + <function name="signal_connect_closure" c:identifier="g_signal_connect_closure"> + <doc xml:space="preserve">Connects a closure to a signal for a particular object.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the handler ID (always greater than 0 for successful connections)</doc> + <type name="gulong" c:type="gulong"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance to connect to.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="detailed_signal" transfer-ownership="none"> + <doc xml:space="preserve">a string of the form "signal-name::detail".</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the closure to connect.</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="after" transfer-ownership="none"> + <doc xml:space="preserve">whether the handler should be called before or after the + default handler of the signal.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="signal_connect_closure_by_id" c:identifier="g_signal_connect_closure_by_id"> + <doc xml:space="preserve">Connects a closure to a signal for a particular object.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the handler ID (always greater than 0 for successful connections)</doc> + <type name="gulong" c:type="gulong"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance to connect to.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="signal_id" transfer-ownership="none"> + <doc xml:space="preserve">the id of the signal.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="detail" transfer-ownership="none"> + <doc xml:space="preserve">the detail.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">the closure to connect.</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="after" transfer-ownership="none"> + <doc xml:space="preserve">whether the handler should be called before or after the + default handler of the signal.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="signal_connect_data" c:identifier="g_signal_connect_data" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the handler ID (always greater than 0 for successful connections)</doc> + <type name="gulong" c:type="gulong"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance to connect to.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="detailed_signal" transfer-ownership="none"> + <doc xml:space="preserve">a string of the form "signal-name::detail".</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="c_handler" transfer-ownership="none" closure="3"> + <doc xml:space="preserve">the #GCallback to connect.</doc> + <type name="Callback" c:type="GCallback"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="2"> + <doc xml:space="preserve">data to pass to @c_handler calls.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy_data" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" destroy="3"> + <doc xml:space="preserve">a #GClosureNotify for @data.</doc> + <type name="ClosureNotify" c:type="GClosureNotify"/> + </parameter> + <parameter name="connect_flags" transfer-ownership="none"> + <doc xml:space="preserve">a combination of #GConnectFlags.</doc> + <type name="ConnectFlags" c:type="GConnectFlags"/> + </parameter> + </parameters> + </function> + <function name="signal_connect_object" c:identifier="g_signal_connect_object" introspectable="0"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the handler id.</doc> + <type name="gulong" c:type="gulong"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance to connect to.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="detailed_signal" transfer-ownership="none"> + <doc xml:space="preserve">a string of the form "signal-name::detail".</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="c_handler" transfer-ownership="none"> + <doc xml:space="preserve">the #GCallback to connect.</doc> + <type name="Callback" c:type="GCallback"/> + </parameter> + <parameter name="gobject" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the object to pass as data + to @c_handler.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="connect_flags" transfer-ownership="none"> + <doc xml:space="preserve">a combination of #GConnectFlags.</doc> + <type name="ConnectFlags" c:type="GConnectFlags"/> + </parameter> + </parameters> + </function> + <function-macro name="signal_connect_swapped" c:identifier="g_signal_connect_swapped" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <parameters> + <parameter name="instance"> + <doc xml:space="preserve">the instance to connect to.</doc> + </parameter> + <parameter name="detailed_signal"> + <doc xml:space="preserve">a string of the form "signal-name::detail".</doc> + </parameter> + <parameter name="c_handler"> + <doc xml:space="preserve">the #GCallback to connect.</doc> + </parameter> + <parameter name="data"> + <doc xml:space="preserve">data to pass to @c_handler calls.</doc> + </parameter> + </parameters> + </function-macro> + <function name="signal_emit" c:identifier="g_signal_emit" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance the signal is being emitted on.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="signal_id" transfer-ownership="none"> + <doc xml:space="preserve">the signal id</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="detail" transfer-ownership="none"> + <doc xml:space="preserve">the detail</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="signal_emit_by_name" c:identifier="g_signal_emit_by_name" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance the signal is being emitted on.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="detailed_signal" transfer-ownership="none"> + <doc xml:space="preserve">a string of the form "signal-name::detail".</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="signal_emit_valist" c:identifier="g_signal_emit_valist" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance the signal is being + emitted on.</doc> + <type name="TypeInstance" c:type="gpointer"/> + </parameter> + <parameter name="signal_id" transfer-ownership="none"> + <doc xml:space="preserve">the signal id</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="detail" transfer-ownership="none"> + <doc xml:space="preserve">the detail</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="var_args" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </function> + <function name="signal_emitv" c:identifier="g_signal_emitv"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="instance_and_params" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <array zero-terminated="0" c:type="const GValue*"> + <type name="Value" c:type="GValue"/> + </array> + </parameter> + <parameter name="signal_id" transfer-ownership="none"> + <doc xml:space="preserve">the signal id</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="detail" transfer-ownership="none"> + <doc xml:space="preserve">the detail</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="return_value" direction="inout" caller-allocates="0" transfer-ownership="full" optional="1"> + <doc xml:space="preserve">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.</doc> + <type name="Value" c:type="GValue*"/> + </parameter> + </parameters> + </function> + <function name="signal_get_invocation_hint" c:identifier="g_signal_get_invocation_hint"> + <doc xml:space="preserve">Returns the invocation hint of the innermost signal emission of instance.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the invocation hint of the innermost + signal emission, or %NULL if not found.</doc> + <type name="SignalInvocationHint" c:type="GSignalInvocationHint*"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the instance to query</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="signal_handler_block" c:identifier="g_signal_handler_block"> + <doc xml:space="preserve">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 deactivate 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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">The instance to block the signal handler of.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="handler_id" transfer-ownership="none"> + <doc xml:space="preserve">Handler id of the handler to be blocked.</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + </parameters> + </function> + <function name="signal_handler_disconnect" c:identifier="g_signal_handler_disconnect"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">The instance to remove the signal handler from.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="handler_id" transfer-ownership="none"> + <doc xml:space="preserve">Handler id of the handler to be disconnected.</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + </parameters> + </function> + <function name="signal_handler_find" c:identifier="g_signal_handler_find"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A valid non-0 signal handler id for a successful match.</doc> + <type name="gulong" c:type="gulong"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">The instance owning the signal handler to be found.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="mask" transfer-ownership="none"> + <doc xml:space="preserve">Mask indicating which of @signal_id, @detail, @closure, @func + and/or @data the handler has to match.</doc> + <type name="SignalMatchType" c:type="GSignalMatchType"/> + </parameter> + <parameter name="signal_id" transfer-ownership="none"> + <doc xml:space="preserve">Signal the handler has to be connected to.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="detail" transfer-ownership="none"> + <doc xml:space="preserve">Signal detail the handler has to be connected to.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The closure the handler will invoke.</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="func" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The C closure callback of the handler (useless for non-C closures).</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">The closure data of the handler's closure.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="signal_handler_is_connected" c:identifier="g_signal_handler_is_connected"> + <doc xml:space="preserve">Returns whether @handler_id is the ID of a handler connected to @instance.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether @handler_id identifies a handler connected to @instance.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">The instance where a signal handler is sought.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="handler_id" transfer-ownership="none"> + <doc xml:space="preserve">the handler ID.</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + </parameters> + </function> + <function name="signal_handler_unblock" c:identifier="g_signal_handler_unblock"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">The instance to unblock the signal handler of.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="handler_id" transfer-ownership="none"> + <doc xml:space="preserve">Handler id of the handler to be unblocked.</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + </parameters> + </function> + <function-macro name="signal_handlers_block_by_func" c:identifier="g_signal_handlers_block_by_func" introspectable="0"> + <doc xml:space="preserve">Blocks all handlers on an instance that match @func and @data.</doc> + <parameters> + <parameter name="instance"> + <doc xml:space="preserve">The instance to block handlers from.</doc> + </parameter> + <parameter name="func"> + <doc xml:space="preserve">The C closure callback of the handlers (useless for non-C closures).</doc> + </parameter> + <parameter name="data"> + <doc xml:space="preserve">The closure data of the handlers' closures.</doc> + </parameter> + </parameters> + </function-macro> + <function name="signal_handlers_block_matched" c:identifier="g_signal_handlers_block_matched"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The number of handlers that matched.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">The instance to block handlers from.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="mask" transfer-ownership="none"> + <doc xml:space="preserve">Mask indicating which of @signal_id, @detail, @closure, @func + and/or @data the handlers have to match.</doc> + <type name="SignalMatchType" c:type="GSignalMatchType"/> + </parameter> + <parameter name="signal_id" transfer-ownership="none"> + <doc xml:space="preserve">Signal the handlers have to be connected to.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="detail" transfer-ownership="none"> + <doc xml:space="preserve">Signal detail the handlers have to be connected to.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The closure the handlers will invoke.</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="func" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The C closure callback of the handlers (useless for non-C closures).</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">The closure data of the handlers' closures.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="signal_handlers_destroy" c:identifier="g_signal_handlers_destroy"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">The instance whose signal handlers are destroyed</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function-macro name="signal_handlers_disconnect_by_data" c:identifier="g_signal_handlers_disconnect_by_data" version="2.32" introspectable="0"> + <doc xml:space="preserve">Disconnects all handlers on an instance that match @data.</doc> + <parameters> + <parameter name="instance"> + <doc xml:space="preserve">The instance to remove handlers from</doc> + </parameter> + <parameter name="data"> + <doc xml:space="preserve">the closure data of the handlers' closures</doc> + </parameter> + </parameters> + </function-macro> + <function-macro name="signal_handlers_disconnect_by_func" c:identifier="g_signal_handlers_disconnect_by_func" introspectable="0"> + <doc xml:space="preserve">Disconnects all handlers on an instance that match @func and @data.</doc> + <parameters> + <parameter name="instance"> + <doc xml:space="preserve">The instance to remove handlers from.</doc> + </parameter> + <parameter name="func"> + <doc xml:space="preserve">The C closure callback of the handlers (useless for non-C closures).</doc> + </parameter> + <parameter name="data"> + <doc xml:space="preserve">The closure data of the handlers' closures.</doc> + </parameter> + </parameters> + </function-macro> + <function name="signal_handlers_disconnect_matched" c:identifier="g_signal_handlers_disconnect_matched"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The number of handlers that matched.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">The instance to remove handlers from.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="mask" transfer-ownership="none"> + <doc xml:space="preserve">Mask indicating which of @signal_id, @detail, @closure, @func + and/or @data the handlers have to match.</doc> + <type name="SignalMatchType" c:type="GSignalMatchType"/> + </parameter> + <parameter name="signal_id" transfer-ownership="none"> + <doc xml:space="preserve">Signal the handlers have to be connected to.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="detail" transfer-ownership="none"> + <doc xml:space="preserve">Signal detail the handlers have to be connected to.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The closure the handlers will invoke.</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="func" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The C closure callback of the handlers (useless for non-C closures).</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">The closure data of the handlers' closures.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function-macro name="signal_handlers_unblock_by_func" c:identifier="g_signal_handlers_unblock_by_func" introspectable="0"> + <doc xml:space="preserve">Unblocks all handlers on an instance that match @func and @data.</doc> + <parameters> + <parameter name="instance"> + <doc xml:space="preserve">The instance to unblock handlers from.</doc> + </parameter> + <parameter name="func"> + <doc xml:space="preserve">The C closure callback of the handlers (useless for non-C closures).</doc> + </parameter> + <parameter name="data"> + <doc xml:space="preserve">The closure data of the handlers' closures.</doc> + </parameter> + </parameters> + </function-macro> + <function name="signal_handlers_unblock_matched" c:identifier="g_signal_handlers_unblock_matched"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The number of handlers that matched.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">The instance to unblock handlers from.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="mask" transfer-ownership="none"> + <doc xml:space="preserve">Mask indicating which of @signal_id, @detail, @closure, @func + and/or @data the handlers have to match.</doc> + <type name="SignalMatchType" c:type="GSignalMatchType"/> + </parameter> + <parameter name="signal_id" transfer-ownership="none"> + <doc xml:space="preserve">Signal the handlers have to be connected to.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="detail" transfer-ownership="none"> + <doc xml:space="preserve">Signal detail the handlers have to be connected to.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The closure the handlers will invoke.</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="func" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The C closure callback of the handlers (useless for non-C closures).</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">The closure data of the handlers' closures.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="signal_has_handler_pending" c:identifier="g_signal_has_handler_pending"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a handler is connected to the signal, %FALSE + otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the object whose signal handlers are sought.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="signal_id" transfer-ownership="none"> + <doc xml:space="preserve">the signal id.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="detail" transfer-ownership="none"> + <doc xml:space="preserve">the detail.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="may_be_blocked" transfer-ownership="none"> + <doc xml:space="preserve">whether blocked handlers should count as match.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="signal_is_valid_name" c:identifier="g_signal_is_valid_name" version="2.66"> + <doc xml:space="preserve">Validate a signal name. This can be useful for dynamically-generated signals +which need to be validated at run-time before actually trying to create them. + +See [canonical parameter names][canonical-parameter-names] for details of +the rules for valid names. The rules for signal names are the same as those +for property names.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @name is a valid signal name, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the canonical name of the signal</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="signal_list_ids" c:identifier="g_signal_list_ids"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">Newly allocated array of signal IDs.</doc> + <array length="1" zero-terminated="0" c:type="guint*"> + <type name="guint" c:type="guint"/> + </array> + </return-value> + <parameters> + <parameter name="itype" transfer-ownership="none"> + <doc xml:space="preserve">Instance or interface type.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_ids" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">Location to store the number of signal ids for @itype.</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </function> + <function name="signal_lookup" c:identifier="g_signal_lookup"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the signal's identifying number, or 0 if no signal was found.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the signal's name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="itype" transfer-ownership="none"> + <doc xml:space="preserve">the type that the signal operates on.</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="signal_name" c:identifier="g_signal_name"> + <doc xml:space="preserve">Given the signal's identifier, finds its name. + +Two different signals may have the same name, if they have differing types.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the signal name, or %NULL if the signal number was invalid.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="signal_id" transfer-ownership="none"> + <doc xml:space="preserve">the signal's identifying number.</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="signal_new" c:identifier="g_signal_new" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the signal id</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="signal_name" transfer-ownership="none"> + <doc xml:space="preserve">the name for the signal</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="itype" transfer-ownership="none"> + <doc xml:space="preserve">the type this signal pertains to. It will also pertain to + types which are derived from this type.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="signal_flags" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="SignalFlags" c:type="GSignalFlags"/> + </parameter> + <parameter name="class_offset" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="accumulator" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the accumulator for this signal; may be %NULL.</doc> + <type name="SignalAccumulator" c:type="GSignalAccumulator"/> + </parameter> + <parameter name="accu_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data for the @accumulator.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="c_marshaller" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the function to translate arrays of parameter + values to signal emissions into C language callback invocations or %NULL.</doc> + <type name="SignalCMarshaller" c:type="GSignalCMarshaller"/> + </parameter> + <parameter name="return_type" transfer-ownership="none"> + <doc xml:space="preserve">the type of return value, or #G_TYPE_NONE for a signal + without a return value.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the number of parameter types to follow.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">a list of types, one for each parameter.</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="signal_new_class_handler" c:identifier="g_signal_new_class_handler" version="2.18" introspectable="0"> + <doc xml:space="preserve">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 overridden 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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the signal id</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="signal_name" transfer-ownership="none"> + <doc xml:space="preserve">the name for the signal</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="itype" transfer-ownership="none"> + <doc xml:space="preserve">the type this signal pertains to. It will also pertain to + types which are derived from this type.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="signal_flags" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="SignalFlags" c:type="GSignalFlags"/> + </parameter> + <parameter name="class_handler" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">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.</doc> + <type name="Callback" c:type="GCallback"/> + </parameter> + <parameter name="accumulator" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the accumulator for this signal; may be %NULL.</doc> + <type name="SignalAccumulator" c:type="GSignalAccumulator"/> + </parameter> + <parameter name="accu_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data for the @accumulator.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="c_marshaller" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the function to translate arrays of parameter + values to signal emissions into C language callback invocations or %NULL.</doc> + <type name="SignalCMarshaller" c:type="GSignalCMarshaller"/> + </parameter> + <parameter name="return_type" transfer-ownership="none"> + <doc xml:space="preserve">the type of return value, or #G_TYPE_NONE for a signal + without a return value.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the number of parameter types to follow.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">a list of types, one for each parameter.</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="signal_new_valist" c:identifier="g_signal_new_valist" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the signal id</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="signal_name" transfer-ownership="none"> + <doc xml:space="preserve">the name for the signal</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="itype" transfer-ownership="none"> + <doc xml:space="preserve">the type this signal pertains to. It will also pertain to + types which are derived from this type.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="signal_flags" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="SignalFlags" c:type="GSignalFlags"/> + </parameter> + <parameter name="class_closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The closure to invoke on signal emission; may be %NULL.</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="accumulator" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the accumulator for this signal; may be %NULL.</doc> + <type name="SignalAccumulator" c:type="GSignalAccumulator"/> + </parameter> + <parameter name="accu_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data for the @accumulator.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="c_marshaller" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the function to translate arrays of parameter + values to signal emissions into C language callback invocations or %NULL.</doc> + <type name="SignalCMarshaller" c:type="GSignalCMarshaller"/> + </parameter> + <parameter name="return_type" transfer-ownership="none"> + <doc xml:space="preserve">the type of return value, or #G_TYPE_NONE for a signal + without a return value.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the number of parameter types in @args.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of #GType, one for each parameter.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </function> + <function name="signal_newv" c:identifier="g_signal_newv" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the signal id</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="signal_name" transfer-ownership="none"> + <doc xml:space="preserve">the name for the signal</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="itype" transfer-ownership="none"> + <doc xml:space="preserve">the type this signal pertains to. It will also pertain to + types which are derived from this type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="signal_flags" transfer-ownership="none"> + <doc xml:space="preserve">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</doc> + <type name="SignalFlags" c:type="GSignalFlags"/> + </parameter> + <parameter name="class_closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The closure to invoke on signal emission; + may be %NULL</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + <parameter name="accumulator" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the accumulator for this signal; may be %NULL</doc> + <type name="SignalAccumulator" c:type="GSignalAccumulator"/> + </parameter> + <parameter name="accu_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data for the @accumulator</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="c_marshaller" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the function to translate arrays of + parameter values to signal emissions into C language callback + invocations or %NULL</doc> + <type name="SignalCMarshaller" c:type="GSignalCMarshaller"/> + </parameter> + <parameter name="return_type" transfer-ownership="none"> + <doc xml:space="preserve">the type of return value, or #G_TYPE_NONE for a signal + without a return value</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_params" transfer-ownership="none"> + <doc xml:space="preserve">the length of @param_types</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="param_types" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an array of types, one for + each parameter (may be %NULL if @n_params is zero)</doc> + <array length="8" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </parameter> + </parameters> + </function> + <function name="signal_override_class_closure" c:identifier="g_signal_override_class_closure"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="signal_id" transfer-ownership="none"> + <doc xml:space="preserve">the signal id</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="instance_type" transfer-ownership="none"> + <doc xml:space="preserve">the instance type on which to override the class closure + for the signal.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="class_closure" transfer-ownership="none"> + <doc xml:space="preserve">the closure.</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + </parameters> + </function> + <function name="signal_override_class_handler" c:identifier="g_signal_override_class_handler" version="2.18" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="signal_name" transfer-ownership="none"> + <doc xml:space="preserve">the name for the signal</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="instance_type" transfer-ownership="none"> + <doc xml:space="preserve">the instance type on which to override the class handler + for the signal.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="class_handler" transfer-ownership="none"> + <doc xml:space="preserve">the handler.</doc> + <type name="Callback" c:type="GCallback"/> + </parameter> + </parameters> + </function> + <function name="signal_parse_name" c:identifier="g_signal_parse_name"> + <doc xml:space="preserve">Internal function to parse a signal name into its @signal_id +and @detail quark.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="detailed_signal" transfer-ownership="none"> + <doc xml:space="preserve">a string of the form "signal-name::detail".</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="itype" transfer-ownership="none"> + <doc xml:space="preserve">The interface/instance type that introduced "signal-name".</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="signal_id_p" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">Location to store the signal id.</doc> + <type name="guint" c:type="guint*"/> + </parameter> + <parameter name="detail_p" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">Location to store the detail quark.</doc> + <type name="GLib.Quark" c:type="GQuark*"/> + </parameter> + <parameter name="force_detail_quark" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE forces creation of a #GQuark for the detail.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="signal_query" c:identifier="g_signal_query"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="signal_id" transfer-ownership="none"> + <doc xml:space="preserve">The signal id of the signal to query information for.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="query" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve">A user provided structure that is + filled in with constant values upon success.</doc> + <type name="SignalQuery" c:type="GSignalQuery*"/> + </parameter> + </parameters> + </function> + <function name="signal_remove_emission_hook" c:identifier="g_signal_remove_emission_hook"> + <doc xml:space="preserve">Deletes an emission hook.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="signal_id" transfer-ownership="none"> + <doc xml:space="preserve">the id of the signal</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="hook_id" transfer-ownership="none"> + <doc xml:space="preserve">the id of the emission hook, as returned by + g_signal_add_emission_hook()</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + </parameters> + </function> + <function name="signal_set_va_marshaller" c:identifier="g_signal_set_va_marshaller" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="signal_id" transfer-ownership="none"> + <doc xml:space="preserve">the signal id</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="instance_type" transfer-ownership="none"> + <doc xml:space="preserve">the instance type on which to set the marshaller.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="va_marshaller" transfer-ownership="none"> + <doc xml:space="preserve">the marshaller to set.</doc> + <type name="SignalCVaMarshaller" c:type="GSignalCVaMarshaller"/> + </parameter> + </parameters> + </function> + <function name="signal_stop_emission" c:identifier="g_signal_stop_emission"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the object whose signal handlers you wish to stop.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="signal_id" transfer-ownership="none"> + <doc xml:space="preserve">the signal identifier, as returned by g_signal_lookup().</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="detail" transfer-ownership="none"> + <doc xml:space="preserve">the detail which the signal was emitted with.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + </parameters> + </function> + <function name="signal_stop_emission_by_name" c:identifier="g_signal_stop_emission_by_name"> + <doc xml:space="preserve">Stops a signal's current emission. + +This is just like g_signal_stop_emission() except it will look up the +signal id for you.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">the object whose signal handlers you wish to stop.</doc> + <type name="Object" c:type="gpointer"/> + </parameter> + <parameter name="detailed_signal" transfer-ownership="none"> + <doc xml:space="preserve">a string of the form "signal-name::detail".</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="signal_type_cclosure_new" c:identifier="g_signal_type_cclosure_new"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a floating reference to a new #GCClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </return-value> + <parameters> + <parameter name="itype" transfer-ownership="none"> + <doc xml:space="preserve">the #GType identifier of an interface or classed type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="struct_offset" transfer-ownership="none"> + <doc xml:space="preserve">the offset of the member function of @itype's class + structure which is to be invoked by the new closure</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <docsection name="signals"> + <doc xml:space="preserve">The basic concept of the signal system is that of the emission +of a signal. Signals are introduced per-type and are identified +through strings. Signals introduced for a parent type are available +in derived types as well, so basically they are a per-type facility +that is inherited. + +A signal emission mainly involves invocation of a certain set of +callbacks in precisely defined manner. There are two main categories +of such callbacks, per-object ones and user provided ones. +(Although signals can deal with any kind of instantiatable type, I'm +referring to those types as "object types" in the following, simply +because that is the context most users will encounter signals in.) +The per-object callbacks are most often referred to as "object method +handler" or "default (signal) handler", while user provided callbacks are +usually just called "signal handler". + +The object method handler is provided at signal creation time (this most +frequently happens at the end of an object class' creation), while user +provided handlers are frequently connected and disconnected to/from a +certain signal on certain object instances. + +A signal emission consists of five stages, unless prematurely stopped: + +1. Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals + +2. Invocation of normal user-provided signal handlers (where the @after + flag is not set) + +3. Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals + +4. Invocation of user provided signal handlers (where the @after flag is set) + +5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals + +The user-provided signal handlers are called in the order they were +connected in. + +All handlers may prematurely stop a signal emission, and any number of +handlers may be connected, disconnected, blocked or unblocked during +a signal emission. + +There are certain criteria for skipping user handlers in stages 2 and 4 +of a signal emission. + +First, user handlers may be blocked. Blocked handlers are omitted during +callback invocation, to return from the blocked state, a handler has to +get unblocked exactly the same amount of times it has been blocked before. + +Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional +@detail argument passed in to g_signal_emit() has to match the detail +argument of the signal handler currently subject to invocation. +Specification of no detail argument for signal handlers (omission of the +detail part of the signal specification upon connection) serves as a +wildcard and matches any detail argument passed in to emission. + +While the @detail argument is typically used to pass an object property name +(as with #GObject::notify), no specific format is mandated for the detail +string, other than that it must be non-empty. + +## Memory management of signal handlers # {#signal-memory-management} + +If you are connecting handlers to signals and using a #GObject instance as +your signal handler user data, you should remember to pair calls to +g_signal_connect() with calls to g_signal_handler_disconnect() or +g_signal_handlers_disconnect_by_func(). While signal handlers are +automatically disconnected when the object emitting the signal is finalised, +they are not automatically disconnected when the signal handler user data is +destroyed. If this user data is a #GObject instance, using it from a +signal handler after it has been finalised is an error. + +There are two strategies for managing such user data. The first is to +disconnect the signal handler (using g_signal_handler_disconnect() or +g_signal_handlers_disconnect_by_func()) when the user data (object) is +finalised; this has to be implemented manually. For non-threaded programs, +g_signal_connect_object() can be used to implement this automatically. +Currently, however, it is unsafe to use in threaded programs. + +The second is to hold a strong reference on the user data until after the +signal is disconnected for other reasons. This can be implemented +automatically using g_signal_connect_data(). + +The first approach is recommended, as the second approach can result in +effective memory leaks of the user data if the signal handler is never +disconnected for some reason.</doc> + </docsection> + <function name="source_set_closure" c:identifier="g_source_set_closure"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">the source</doc> + <type name="GLib.Source" c:type="GSource*"/> + </parameter> + <parameter name="closure" transfer-ownership="none"> + <doc xml:space="preserve">a #GClosure</doc> + <type name="Closure" c:type="GClosure*"/> + </parameter> + </parameters> + </function> + <function name="source_set_dummy_callback" c:identifier="g_source_set_dummy_callback"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">the source</doc> + <type name="GLib.Source" c:type="GSource*"/> + </parameter> + </parameters> + </function> + <function name="strdup_value_contents" c:identifier="g_strdup_value_contents"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">Newly allocated string.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">#GValue which contents are to be described.</doc> + <type name="Value" c:type="const GValue*"/> + </parameter> + </parameters> + </function> + <function name="type_add_class_cache_func" c:identifier="g_type_add_class_cache_func" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="cache_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to be passed to @cache_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="cache_func" transfer-ownership="none"> + <doc xml:space="preserve">a #GTypeClassCacheFunc</doc> + <type name="TypeClassCacheFunc" c:type="GTypeClassCacheFunc"/> + </parameter> + </parameters> + </function> + <function name="type_add_class_private" c:identifier="g_type_add_class_private" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="class_type" transfer-ownership="none"> + <doc xml:space="preserve">GType of a classed type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="private_size" transfer-ownership="none"> + <doc xml:space="preserve">size of private structure</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="type_add_instance_private" c:identifier="g_type_add_instance_private"> + <return-value transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="class_type" transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="private_size" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <function name="type_add_interface_check" c:identifier="g_type_add_interface_check" version="2.4" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="check_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @check_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="check_func" transfer-ownership="none"> + <doc xml:space="preserve">function to be called after each interface + is initialized</doc> + <type name="TypeInterfaceCheckFunc" c:type="GTypeInterfaceCheckFunc"/> + </parameter> + </parameters> + </function> + <function name="type_add_interface_dynamic" c:identifier="g_type_add_interface_dynamic"> + <doc xml:space="preserve">Adds @interface_type to the dynamic @instance_type. The information +contained in the #GTypePlugin structure pointed to by @plugin +is used to manage the relationship.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="instance_type" transfer-ownership="none"> + <doc xml:space="preserve">#GType value of an instantiatable type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="interface_type" transfer-ownership="none"> + <doc xml:space="preserve">#GType value of an interface type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="plugin" transfer-ownership="none"> + <doc xml:space="preserve">#GTypePlugin structure to retrieve the #GInterfaceInfo from</doc> + <type name="TypePlugin" c:type="GTypePlugin*"/> + </parameter> + </parameters> + </function> + <function name="type_add_interface_static" c:identifier="g_type_add_interface_static"> + <doc xml:space="preserve">Adds @interface_type to the static @instance_type. +The information contained in the #GInterfaceInfo structure +pointed to by @info is used to manage the relationship.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="instance_type" transfer-ownership="none"> + <doc xml:space="preserve">#GType value of an instantiatable type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="interface_type" transfer-ownership="none"> + <doc xml:space="preserve">#GType value of an interface type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">#GInterfaceInfo structure for this + (@instance_type, @interface_type) combination</doc> + <type name="InterfaceInfo" c:type="const GInterfaceInfo*"/> + </parameter> + </parameters> + </function> + <function name="type_check_class_cast" c:identifier="g_type_check_class_cast" introspectable="0"> + <return-value> + <type name="TypeClass" c:type="GTypeClass*"/> + </return-value> + <parameters> + <parameter name="g_class" transfer-ownership="none"> + <type name="TypeClass" c:type="GTypeClass*"/> + </parameter> + <parameter name="is_a_type" transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_check_class_is_a" c:identifier="g_type_check_class_is_a"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="g_class" transfer-ownership="none"> + <type name="TypeClass" c:type="GTypeClass*"/> + </parameter> + <parameter name="is_a_type" transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_check_instance" c:identifier="g_type_check_instance"> + <doc xml:space="preserve">Private helper function to aid implementation of the +G_TYPE_CHECK_INSTANCE() macro.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @instance is valid, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">a valid #GTypeInstance structure</doc> + <type name="TypeInstance" c:type="GTypeInstance*"/> + </parameter> + </parameters> + </function> + <function name="type_check_instance_cast" c:identifier="g_type_check_instance_cast" introspectable="0"> + <return-value> + <type name="TypeInstance" c:type="GTypeInstance*"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <type name="TypeInstance" c:type="GTypeInstance*"/> + </parameter> + <parameter name="iface_type" transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_check_instance_is_a" c:identifier="g_type_check_instance_is_a"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <type name="TypeInstance" c:type="GTypeInstance*"/> + </parameter> + <parameter name="iface_type" transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_check_instance_is_fundamentally_a" c:identifier="g_type_check_instance_is_fundamentally_a"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <type name="TypeInstance" c:type="GTypeInstance*"/> + </parameter> + <parameter name="fundamental_type" transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_check_is_value_type" c:identifier="g_type_check_is_value_type"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_check_value" c:identifier="g_type_check_value"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="const GValue*"/> + </parameter> + </parameters> + </function> + <function name="type_check_value_holds" c:identifier="g_type_check_value_holds"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <type name="Value" c:type="const GValue*"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_children" c:identifier="g_type_children"> + <doc xml:space="preserve">Return a newly allocated and 0-terminated array of type IDs, listing +the child types of @type.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">Newly allocated + and 0-terminated array of child types, free with g_free()</doc> + <array length="1" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">the parent type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_children" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the length of + the returned array, or %NULL</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </function> + <function name="type_class_adjust_private_offset" c:identifier="g_type_class_adjust_private_offset" moved-to="TypeClass.adjust_private_offset"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="g_class" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="private_size_or_offset" transfer-ownership="none"> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </function> + <function name="type_class_peek" c:identifier="g_type_class_peek" moved-to="TypeClass.peek"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GTypeClass + structure for the given type ID or %NULL if the class does not + currently exist</doc> + <type name="TypeClass" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">type ID of a classed type</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_class_peek_static" c:identifier="g_type_class_peek_static" moved-to="TypeClass.peek_static" version="2.4"> + <doc xml:space="preserve">A more efficient version of g_type_class_peek() which works only for +static types.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GTypeClass + structure for the given type ID or %NULL if the class does not + currently exist or is dynamically loaded</doc> + <type name="TypeClass" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">type ID of a classed type</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_class_ref" c:identifier="g_type_class_ref" moved-to="TypeClass.ref"> + <doc xml:space="preserve">Increments the reference count of the class structure belonging to +@type. This function will demand-create the class if it doesn't +exist already.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GTypeClass + structure for the given type ID</doc> + <type name="TypeClass" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">type ID of a classed type</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_create_instance" c:identifier="g_type_create_instance" introspectable="0"> + <doc xml:space="preserve">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 +implementers 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.</doc> + <return-value> + <doc xml:space="preserve">an allocated and initialized instance, subject to further + treatment by the fundamental type implementation</doc> + <type name="TypeInstance" c:type="GTypeInstance*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">an instantiatable type to create an instance for</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_default_interface_peek" c:identifier="g_type_default_interface_peek" version="2.4"> + <doc xml:space="preserve">If the interface type @g_type is currently in use, returns its +default interface vtable.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the default + vtable for the interface, or %NULL if the type is not currently + in use</doc> + <type name="TypeInterface" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="g_type" transfer-ownership="none"> + <doc xml:space="preserve">an interface type</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_default_interface_ref" c:identifier="g_type_default_interface_ref" version="2.4"> + <doc xml:space="preserve">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 initialized 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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the default + vtable for the interface; call g_type_default_interface_unref() + when you are done using the interface.</doc> + <type name="TypeInterface" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="g_type" transfer-ownership="none"> + <doc xml:space="preserve">an interface type</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_default_interface_unref" c:identifier="g_type_default_interface_unref" version="2.4"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="g_iface" transfer-ownership="none"> + <doc xml:space="preserve">the default vtable + structure for an interface, as returned by g_type_default_interface_ref()</doc> + <type name="TypeInterface" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="type_depth" c:identifier="g_type_depth"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the depth of @type</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_ensure" c:identifier="g_type_ensure" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_free_instance" c:identifier="g_type_free_instance"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <doc xml:space="preserve">an instance of a type</doc> + <type name="TypeInstance" c:type="GTypeInstance*"/> + </parameter> + </parameters> + </function> + <function name="type_from_name" c:identifier="g_type_from_name"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">corresponding type ID or 0</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">type name to look up</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="type_fundamental" c:identifier="g_type_fundamental"> + <doc xml:space="preserve">Internal function, used to extract the fundamental type ID portion. +Use G_TYPE_FUNDAMENTAL() instead.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">fundamental type ID</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <parameter name="type_id" transfer-ownership="none"> + <doc xml:space="preserve">valid type ID</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_fundamental_next" c:identifier="g_type_fundamental_next"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the next available fundamental type ID to be registered, + or 0 if the type system ran out of fundamental type IDs</doc> + <type name="GType" c:type="GType"/> + </return-value> + </function> + <function name="type_get_instance_count" c:identifier="g_type_get_instance_count" version="2.44"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of instances allocated of the given type; + if instance counts are not available, returns 0.</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_get_plugin" c:identifier="g_type_get_plugin"> + <doc xml:space="preserve">Returns the #GTypePlugin structure for @type.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the corresponding plugin + if @type is a dynamic type, %NULL otherwise</doc> + <type name="TypePlugin" c:type="GTypePlugin*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">#GType to retrieve the plugin for</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_get_qdata" c:identifier="g_type_get_qdata"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the data, or %NULL if no data was found</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="quark" transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark id to identify the data</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + </parameters> + </function> + <function name="type_get_type_registration_serial" c:identifier="g_type_get_type_registration_serial" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">An unsigned int, representing the state of type registrations</doc> + <type name="guint" c:type="guint"/> + </return-value> + </function> + <function name="type_init" c:identifier="g_type_init" deprecated="1" deprecated-version="2.36"> + <doc xml:space="preserve">This function used to initialise the type system. Since GLib 2.36, +the type system is initialised automatically and this function does +nothing.</doc> + <doc-deprecated xml:space="preserve">the type system is now initialised automatically</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </function> + <function name="type_init_with_debug_flags" c:identifier="g_type_init_with_debug_flags" deprecated="1" deprecated-version="2.36"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">the type system is now initialised automatically</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="debug_flags" transfer-ownership="none"> + <doc xml:space="preserve">bitwise combination of #GTypeDebugFlags values for + debugging purposes</doc> + <type name="TypeDebugFlags" c:type="GTypeDebugFlags"/> + </parameter> + </parameters> + </function> + <function name="type_interface_add_prerequisite" c:identifier="g_type_interface_add_prerequisite" moved-to="TypeInterface.add_prerequisite"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="interface_type" transfer-ownership="none"> + <doc xml:space="preserve">#GType value of an interface type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="prerequisite_type" transfer-ownership="none"> + <doc xml:space="preserve">#GType value of an interface or instantiatable type</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_interface_get_plugin" c:identifier="g_type_interface_get_plugin" moved-to="TypeInterface.get_plugin"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GTypePlugin for the dynamic + interface @interface_type of @instance_type</doc> + <type name="TypePlugin" c:type="GTypePlugin*"/> + </return-value> + <parameters> + <parameter name="instance_type" transfer-ownership="none"> + <doc xml:space="preserve">#GType of an instantiatable type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="interface_type" transfer-ownership="none"> + <doc xml:space="preserve">#GType of an interface type</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_interface_peek" c:identifier="g_type_interface_peek" moved-to="TypeInterface.peek"> + <doc xml:space="preserve">Returns the #GTypeInterface structure of an interface to which the +passed in class conforms.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GTypeInterface + structure of @iface_type if implemented by @instance_class, %NULL + otherwise</doc> + <type name="TypeInterface" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="instance_class" transfer-ownership="none"> + <doc xml:space="preserve">a #GTypeClass structure</doc> + <type name="TypeClass" c:type="gpointer"/> + </parameter> + <parameter name="iface_type" transfer-ownership="none"> + <doc xml:space="preserve">an interface ID which this class conforms to</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_interface_prerequisites" c:identifier="g_type_interface_prerequisites" moved-to="TypeInterface.prerequisites" version="2.2"> + <doc xml:space="preserve">Returns the prerequisites of an interfaces type.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a + newly-allocated zero-terminated array of #GType containing + the prerequisites of @interface_type</doc> + <array length="1" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </return-value> + <parameters> + <parameter name="interface_type" transfer-ownership="none"> + <doc xml:space="preserve">an interface type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_prerequisites" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to return the number + of prerequisites, or %NULL</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </function> + <function name="type_interfaces" c:identifier="g_type_interfaces"> + <doc xml:space="preserve">Return a newly allocated and 0-terminated array of type IDs, listing +the interface types that @type conforms to.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">Newly allocated + and 0-terminated array of interface types, free with g_free()</doc> + <array length="1" zero-terminated="0" c:type="GType*"> + <type name="GType" c:type="GType"/> + </array> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">the type to list interface types for</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_interfaces" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the length of + the returned array, or %NULL</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </function> + <function name="type_is_a" c:identifier="g_type_is_a"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @type is a @is_a_type</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">type to check ancestry for</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="is_a_type" transfer-ownership="none"> + <doc xml:space="preserve">possible ancestor of @type or interface that @type + could conform to</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_name" c:identifier="g_type_name"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">static type name or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">type to return name for</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_name_from_class" c:identifier="g_type_name_from_class"> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="g_class" transfer-ownership="none"> + <type name="TypeClass" c:type="GTypeClass*"/> + </parameter> + </parameters> + </function> + <function name="type_name_from_instance" c:identifier="g_type_name_from_instance"> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="instance" transfer-ownership="none"> + <type name="TypeInstance" c:type="GTypeInstance*"/> + </parameter> + </parameters> + </function> + <function name="type_next_base" c:identifier="g_type_next_base"> + <doc xml:space="preserve">Given a @leaf_type and a @root_type which is contained in its +ancestry, 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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">immediate child of @root_type and ancestor of @leaf_type</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <parameter name="leaf_type" transfer-ownership="none"> + <doc xml:space="preserve">descendant of @root_type and the type to be returned</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="root_type" transfer-ownership="none"> + <doc xml:space="preserve">immediate parent of the returned type</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_parent" c:identifier="g_type_parent"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the parent type</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">the derived type</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_qname" c:identifier="g_type_qname"> + <doc xml:space="preserve">Get the corresponding quark of the type IDs name.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the type names quark or 0</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">type to return quark of type name for</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="type_query" c:identifier="g_type_query"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">#GType of a static, classed type</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="query" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve">a user provided structure that is + filled in with constant values upon success</doc> + <type name="TypeQuery" c:type="GTypeQuery*"/> + </parameter> + </parameters> + </function> + <function name="type_register_dynamic" c:identifier="g_type_register_dynamic"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the new type identifier or #G_TYPE_INVALID if registration failed</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <parameter name="parent_type" transfer-ownership="none"> + <doc xml:space="preserve">type from which this type will be derived</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="type_name" transfer-ownership="none"> + <doc xml:space="preserve">0-terminated string used as the name of the new type</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="plugin" transfer-ownership="none"> + <doc xml:space="preserve">#GTypePlugin structure to retrieve the #GTypeInfo from</doc> + <type name="TypePlugin" c:type="GTypePlugin*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">bitwise combination of #GTypeFlags values</doc> + <type name="TypeFlags" c:type="GTypeFlags"/> + </parameter> + </parameters> + </function> + <function name="type_register_fundamental" c:identifier="g_type_register_fundamental"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the predefined type identifier</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <parameter name="type_id" transfer-ownership="none"> + <doc xml:space="preserve">a predefined type identifier</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="type_name" transfer-ownership="none"> + <doc xml:space="preserve">0-terminated string used as the name of the new type</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">#GTypeInfo structure for this type</doc> + <type name="TypeInfo" c:type="const GTypeInfo*"/> + </parameter> + <parameter name="finfo" transfer-ownership="none"> + <doc xml:space="preserve">#GTypeFundamentalInfo structure for this type</doc> + <type name="TypeFundamentalInfo" c:type="const GTypeFundamentalInfo*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">bitwise combination of #GTypeFlags values</doc> + <type name="TypeFlags" c:type="GTypeFlags"/> + </parameter> + </parameters> + </function> + <function name="type_register_static" c:identifier="g_type_register_static"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the new type identifier</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <parameter name="parent_type" transfer-ownership="none"> + <doc xml:space="preserve">type from which this type will be derived</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="type_name" transfer-ownership="none"> + <doc xml:space="preserve">0-terminated string used as the name of the new type</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">#GTypeInfo structure for this type</doc> + <type name="TypeInfo" c:type="const GTypeInfo*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">bitwise combination of #GTypeFlags values</doc> + <type name="TypeFlags" c:type="GTypeFlags"/> + </parameter> + </parameters> + </function> + <function name="type_register_static_simple" c:identifier="g_type_register_static_simple" version="2.12" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the new type identifier</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <parameter name="parent_type" transfer-ownership="none"> + <doc xml:space="preserve">type from which this type will be derived</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="type_name" transfer-ownership="none"> + <doc xml:space="preserve">0-terminated string used as the name of the new type</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="class_size" transfer-ownership="none"> + <doc xml:space="preserve">size of the class structure (see #GTypeInfo)</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="class_init" transfer-ownership="none"> + <doc xml:space="preserve">location of the class initialization function (see #GTypeInfo)</doc> + <type name="ClassInitFunc" c:type="GClassInitFunc"/> + </parameter> + <parameter name="instance_size" transfer-ownership="none"> + <doc xml:space="preserve">size of the instance structure (see #GTypeInfo)</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="instance_init" transfer-ownership="none"> + <doc xml:space="preserve">location of the instance initialization function (see #GTypeInfo)</doc> + <type name="InstanceInitFunc" c:type="GInstanceInitFunc"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">bitwise combination of #GTypeFlags values</doc> + <type name="TypeFlags" c:type="GTypeFlags"/> + </parameter> + </parameters> + </function> + <function name="type_remove_class_cache_func" c:identifier="g_type_remove_class_cache_func" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="cache_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data that was given when adding @cache_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="cache_func" transfer-ownership="none"> + <doc xml:space="preserve">a #GTypeClassCacheFunc</doc> + <type name="TypeClassCacheFunc" c:type="GTypeClassCacheFunc"/> + </parameter> + </parameters> + </function> + <function name="type_remove_interface_check" c:identifier="g_type_remove_interface_check" version="2.4" introspectable="0"> + <doc xml:space="preserve">Removes an interface check function added with +g_type_add_interface_check().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="check_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">callback data passed to g_type_add_interface_check()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="check_func" transfer-ownership="none"> + <doc xml:space="preserve">callback function passed to g_type_add_interface_check()</doc> + <type name="TypeInterfaceCheckFunc" c:type="GTypeInterfaceCheckFunc"/> + </parameter> + </parameters> + </function> + <function name="type_set_qdata" c:identifier="g_type_set_qdata"> + <doc xml:space="preserve">Attaches arbitrary data to a type.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="quark" transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark id to identify the data</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="type_test_flags" c:identifier="g_type_test_flags"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="type_value_table_peek" c:identifier="g_type_value_table_peek" moved-to="TypeValueTable.peek" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">location of the #GTypeValueTable associated with @type or + %NULL if there is no #GTypeValueTable associated with @type</doc> + <type name="TypeValueTable" c:type="GTypeValueTable*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <docsection name="value_arrays"> + <doc xml:space="preserve">The prime purpose of a #GValueArray is for it to be used as an +object property that holds an array of values. A #GValueArray wraps +an array of #GValue elements in order for it to be used as a boxed +type through %G_TYPE_VALUE_ARRAY. + +#GValueArray is deprecated in favour of #GArray since GLib 2.32. It +is possible to create a #GArray that behaves like a #GValueArray by +using the size of #GValue as the element size, and by setting +g_value_unset() as the clear function using g_array_set_clear_func(), +for instance, the following code: + +|[<!-- language="C" --> + GValueArray *array = g_value_array_new (10); +]| + +can be replaced by: + +|[<!-- language="C" --> + GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10); + g_array_set_clear_func (array, (GDestroyNotify) g_value_unset); +]|</doc> + </docsection> + <function name="value_register_transform_func" c:identifier="g_value_register_transform_func" moved-to="Value.register_transform_func" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="src_type" transfer-ownership="none"> + <doc xml:space="preserve">Source type.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="dest_type" transfer-ownership="none"> + <doc xml:space="preserve">Target type.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="transform_func" transfer-ownership="none"> + <doc xml:space="preserve">a function which transforms values of type @src_type + into value of type @dest_type</doc> + <type name="ValueTransform" c:type="GValueTransform"/> + </parameter> + </parameters> + </function> + <function name="value_type_compatible" c:identifier="g_value_type_compatible" moved-to="Value.type_compatible"> + <doc xml:space="preserve">Returns whether a #GValue of type @src_type can be copied into +a #GValue of type @dest_type.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if g_value_copy() is possible with @src_type and @dest_type.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="src_type" transfer-ownership="none"> + <doc xml:space="preserve">source type to be copied.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="dest_type" transfer-ownership="none"> + <doc xml:space="preserve">destination type for copying.</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + <function name="value_type_transformable" c:identifier="g_value_type_transformable" moved-to="Value.type_transformable"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the transformation is possible, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="src_type" transfer-ownership="none"> + <doc xml:space="preserve">Source type.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="dest_type" transfer-ownership="none"> + <doc xml:space="preserve">Target type.</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </function> + </namespace> +</repository> diff --git a/rust-bindings/gir-files/Gio-2.0.gir b/rust-bindings/gir-files/Gio-2.0.gir new file mode 100644 index 0000000000..6c39646b7f --- /dev/null +++ b/rust-bindings/gir-files/Gio-2.0.gir @@ -0,0 +1,86029 @@ +<?xml version="1.0"?> +<!-- This file was automatically generated from C sources - DO NOT EDIT! +To affect the contents of this file, edit the original C definitions, +and/or use gtk-doc annotations. --> +<repository xmlns="http://www.gtk.org/introspection/core/1.0" xmlns:c="http://www.gtk.org/introspection/c/1.0" xmlns:glib="http://www.gtk.org/introspection/glib/1.0" version="1.2"> + <include name="GObject" version="2.0"/> + <package name="gio-2.0"/> + <package name="gio-unix-2.0"/> + <c:include name="gio/gdesktopappinfo.h"/> + <c:include name="gio/gfiledescriptorbased.h"/> + <c:include name="gio/gio.h"/> + <c:include name="gio/gunixconnection.h"/> + <c:include name="gio/gunixcredentialsmessage.h"/> + <c:include name="gio/gunixfdlist.h"/> + <c:include name="gio/gunixfdmessage.h"/> + <c:include name="gio/gunixinputstream.h"/> + <c:include name="gio/gunixmounts.h"/> + <c:include name="gio/gunixoutputstream.h"/> + <c:include name="gio/gunixsocketaddress.h"/> + <namespace name="Gio" version="2.0" shared-library="libgio-2.0.so.0" c:identifier-prefixes="G" c:symbol-prefixes="g"> + <function-macro name="ACTION" c:identifier="G_ACTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ACTION_GET_IFACE" c:identifier="G_ACTION_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ACTION_GROUP" c:identifier="G_ACTION_GROUP" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ACTION_GROUP_GET_IFACE" c:identifier="G_ACTION_GROUP_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ACTION_MAP" c:identifier="G_ACTION_MAP" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ACTION_MAP_GET_IFACE" c:identifier="G_ACTION_MAP_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="APPLICATION" c:identifier="G_APPLICATION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="APPLICATION_CLASS" c:identifier="G_APPLICATION_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="APPLICATION_COMMAND_LINE" c:identifier="G_APPLICATION_COMMAND_LINE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="APPLICATION_COMMAND_LINE_CLASS" c:identifier="G_APPLICATION_COMMAND_LINE_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="APPLICATION_COMMAND_LINE_GET_CLASS" c:identifier="G_APPLICATION_COMMAND_LINE_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="APPLICATION_GET_CLASS" c:identifier="G_APPLICATION_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="APP_INFO" c:identifier="G_APP_INFO" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="APP_INFO_GET_IFACE" c:identifier="G_APP_INFO_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="APP_INFO_MONITOR" c:identifier="G_APP_INFO_MONITOR" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="APP_LAUNCH_CONTEXT" c:identifier="G_APP_LAUNCH_CONTEXT" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="APP_LAUNCH_CONTEXT_CLASS" c:identifier="G_APP_LAUNCH_CONTEXT_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="APP_LAUNCH_CONTEXT_GET_CLASS" c:identifier="G_APP_LAUNCH_CONTEXT_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ASYNC_INITABLE" c:identifier="G_ASYNC_INITABLE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ASYNC_INITABLE_GET_IFACE" c:identifier="G_ASYNC_INITABLE_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ASYNC_RESULT" c:identifier="G_ASYNC_RESULT" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ASYNC_RESULT_GET_IFACE" c:identifier="G_ASYNC_RESULT_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <interface name="Action" c:symbol-prefix="action" c:type="GAction" glib:type-name="GAction" glib:get-type="g_action_get_type" glib:type-struct="ActionInterface"> + <doc xml:space="preserve">#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.</doc> + <function name="name_is_valid" c:identifier="g_action_name_is_valid" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @action_name is valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">a potential action name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="parse_detailed_name" c:identifier="g_action_parse_detailed_name" version="2.38" throws="1"> + <doc xml:space="preserve">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 '.'.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful, else %FALSE with @error set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="detailed_name" transfer-ownership="none"> + <doc xml:space="preserve">a detailed action name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="action_name" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the action name</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="target_value" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the target value, or %NULL for no target</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + </parameters> + </function> + <function name="print_detailed_name" c:identifier="g_action_print_detailed_name" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a detailed format string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">a valid action name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="target_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant target value, or %NULL</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <virtual-method name="activate" invoker="activate" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </instance-parameter> + <parameter name="parameter" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the parameter to the activation</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="change_state" invoker="change_state" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the new state</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_enabled" invoker="get_enabled" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether the action is enabled</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_name" invoker="get_name" version="2.28"> + <doc xml:space="preserve">Queries the name of @action.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the name of the action</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_parameter_type" invoker="get_parameter_type" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the parameter type</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <instance-parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_state" invoker="get_state" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the current state of the action</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_state_hint" invoker="get_state_hint" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the state range hint</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_state_type" invoker="get_state_type" version="2.28"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the state type, if the action is stateful</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <instance-parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="activate" c:identifier="g_action_activate" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </instance-parameter> + <parameter name="parameter" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the parameter to the activation</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="change_state" c:identifier="g_action_change_state" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the new state</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="get_enabled" c:identifier="g_action_get_enabled" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether the action is enabled</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_name" c:identifier="g_action_get_name" version="2.28"> + <doc xml:space="preserve">Queries the name of @action.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the name of the action</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_parameter_type" c:identifier="g_action_get_parameter_type" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the parameter type</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <instance-parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_state" c:identifier="g_action_get_state" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the current state of the action</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_state_hint" c:identifier="g_action_get_state_hint" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the state range hint</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_state_type" c:identifier="g_action_get_state_type" version="2.28"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the state type, if the action is stateful</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <instance-parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </instance-parameter> + </parameters> + </method> + <property name="enabled" version="2.28" transfer-ownership="none"> + <doc xml:space="preserve">If @action is currently enabled. + +If the action is disabled then calls to g_action_activate() and +g_action_change_state() have no effect.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="name" version="2.28" transfer-ownership="none"> + <doc xml:space="preserve">The name of the action. This is mostly meaningful for identifying +the action once it has been added to a #GActionGroup. It is immutable.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="parameter-type" version="2.28" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="GLib.VariantType"/> + </property> + <property name="state" version="2.28" transfer-ownership="none"> + <doc xml:space="preserve">The state of the action, or %NULL if the action is stateless.</doc> + <type name="GLib.Variant"/> + </property> + <property name="state-type" version="2.28" transfer-ownership="none"> + <doc xml:space="preserve">The #GVariantType of the state that the action has, or %NULL if the +action is stateless. This is immutable.</doc> + <type name="GLib.VariantType"/> + </property> + </interface> + <record name="ActionEntry" c:type="GActionEntry"> + <doc xml:space="preserve">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.</doc> + <field name="name" writable="1"> + <doc xml:space="preserve">the name of the action</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="activate"> + <callback name="activate"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="action" transfer-ownership="none"> + <type name="SimpleAction" c:type="GSimpleAction*"/> + </parameter> + <parameter name="parameter" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="parameter_type" writable="1"> + <doc xml:space="preserve">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)</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="state" writable="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + <field name="change_state"> + <callback name="change_state"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="action" transfer-ownership="none"> + <type name="SimpleAction" c:type="GSimpleAction*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="3"> + <type name="gsize" c:type="gsize"/> + </array> + </field> + </record> + <interface name="ActionGroup" c:symbol-prefix="action_group" c:type="GActionGroup" glib:type-name="GActionGroup" glib:get-type="g_action_group_get_type" glib:type-struct="ActionGroupInterface"> + <doc xml:space="preserve">#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().</doc> + <virtual-method name="action_added" invoker="action_added" version="2.28"> + <doc xml:space="preserve">Emits the #GActionGroup::action-added signal on @action_group. + +This function should only be called by #GActionGroup implementations.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action in the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="action_enabled_changed" invoker="action_enabled_changed" version="2.28"> + <doc xml:space="preserve">Emits the #GActionGroup::action-enabled-changed signal on @action_group. + +This function should only be called by #GActionGroup implementations.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action in the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="enabled" transfer-ownership="none"> + <doc xml:space="preserve">whether or not the action is now enabled</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="action_removed" invoker="action_removed" version="2.28"> + <doc xml:space="preserve">Emits the #GActionGroup::action-removed signal on @action_group. + +This function should only be called by #GActionGroup implementations.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action in the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="action_state_changed" invoker="action_state_changed" version="2.28"> + <doc xml:space="preserve">Emits the #GActionGroup::action-state-changed signal on @action_group. + +This function should only be called by #GActionGroup implementations.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action in the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="state" transfer-ownership="none"> + <doc xml:space="preserve">the new state of the named action</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="activate_action" invoker="activate_action" version="2.28"> + <doc xml:space="preserve">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(). + +If the #GActionGroup implementation supports asynchronous remote +activation over D-Bus, this call may return before the relevant +D-Bus traffic has been sent, or any replies have been received. In +order to block on such asynchronous activation calls, +g_dbus_connection_flush() should be called prior to the code, which +depends on the result of the action activation. Without flushing +the D-Bus connection, there is no guarantee that the action would +have been activated. + +The following code which runs in a remote app instance, shows an +example of a "quit" action being activated on the primary app +instance over D-Bus. Here g_dbus_connection_flush() is called +before `exit()`. Without g_dbus_connection_flush(), the "quit" action +may fail to be activated on the primary instance. + +|[<!-- language="C" --> +// call "quit" action on primary instance +g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL); + +// make sure the action is activated now +g_dbus_connection_flush (...); + +g_debug ("application has been terminated. exiting."); + +exit (0); +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to activate</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameter" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">parameters to the activation</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="change_action_state" invoker="change_action_state" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to request the change on</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the new state</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_action_enabled" invoker="get_action_enabled" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether or not the action is currently enabled</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_action_parameter_type" invoker="get_action_parameter_type" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the parameter type</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_action_state" invoker="get_action_state" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the current state of the action</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_action_state_hint" invoker="get_action_state_hint" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the state range hint</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_action_state_type" invoker="get_action_state_type" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the state type, if the action is stateful</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="has_action" invoker="has_action" version="2.28"> + <doc xml:space="preserve">Checks if the named action exists within @action_group.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether the named action exists</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to check for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="list_actions" invoker="list_actions" version="2.28"> + <doc xml:space="preserve">Lists the actions contained within @action_group. + +The caller is responsible for freeing the list with g_strfreev() when +it is no longer required.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated array of the names of the +actions in the group</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="query_action" invoker="query_action" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the action exists, else %FALSE</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action in the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="enabled" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">if the action is presently enabled</doc> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + <parameter name="parameter_type" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the parameter type, or %NULL if none needed</doc> + <type name="GLib.VariantType" c:type="const GVariantType**"/> + </parameter> + <parameter name="state_type" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the state type, or %NULL if stateless</doc> + <type name="GLib.VariantType" c:type="const GVariantType**"/> + </parameter> + <parameter name="state_hint" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the state hint, or %NULL if none</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + <parameter name="state" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the current state, or %NULL if stateless</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + </parameters> + </virtual-method> + <method name="action_added" c:identifier="g_action_group_action_added" version="2.28"> + <doc xml:space="preserve">Emits the #GActionGroup::action-added signal on @action_group. + +This function should only be called by #GActionGroup implementations.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action in the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="action_enabled_changed" c:identifier="g_action_group_action_enabled_changed" version="2.28"> + <doc xml:space="preserve">Emits the #GActionGroup::action-enabled-changed signal on @action_group. + +This function should only be called by #GActionGroup implementations.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action in the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="enabled" transfer-ownership="none"> + <doc xml:space="preserve">whether or not the action is now enabled</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="action_removed" c:identifier="g_action_group_action_removed" version="2.28"> + <doc xml:space="preserve">Emits the #GActionGroup::action-removed signal on @action_group. + +This function should only be called by #GActionGroup implementations.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action in the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="action_state_changed" c:identifier="g_action_group_action_state_changed" version="2.28"> + <doc xml:space="preserve">Emits the #GActionGroup::action-state-changed signal on @action_group. + +This function should only be called by #GActionGroup implementations.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action in the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="state" transfer-ownership="none"> + <doc xml:space="preserve">the new state of the named action</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="activate_action" c:identifier="g_action_group_activate_action" version="2.28"> + <doc xml:space="preserve">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(). + +If the #GActionGroup implementation supports asynchronous remote +activation over D-Bus, this call may return before the relevant +D-Bus traffic has been sent, or any replies have been received. In +order to block on such asynchronous activation calls, +g_dbus_connection_flush() should be called prior to the code, which +depends on the result of the action activation. Without flushing +the D-Bus connection, there is no guarantee that the action would +have been activated. + +The following code which runs in a remote app instance, shows an +example of a "quit" action being activated on the primary app +instance over D-Bus. Here g_dbus_connection_flush() is called +before `exit()`. Without g_dbus_connection_flush(), the "quit" action +may fail to be activated on the primary instance. + +|[<!-- language="C" --> +// call "quit" action on primary instance +g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL); + +// make sure the action is activated now +g_dbus_connection_flush (...); + +g_debug ("application has been terminated. exiting."); + +exit (0); +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to activate</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameter" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">parameters to the activation</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="change_action_state" c:identifier="g_action_group_change_action_state" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to request the change on</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the new state</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="get_action_enabled" c:identifier="g_action_group_get_action_enabled" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether or not the action is currently enabled</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_action_parameter_type" c:identifier="g_action_group_get_action_parameter_type" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the parameter type</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_action_state" c:identifier="g_action_group_get_action_state" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the current state of the action</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_action_state_hint" c:identifier="g_action_group_get_action_state_hint" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the state range hint</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_action_state_type" c:identifier="g_action_group_get_action_state_type" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the state type, if the action is stateful</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="has_action" c:identifier="g_action_group_has_action" version="2.28"> + <doc xml:space="preserve">Checks if the named action exists within @action_group.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether the named action exists</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to check for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="list_actions" c:identifier="g_action_group_list_actions" version="2.28"> + <doc xml:space="preserve">Lists the actions contained within @action_group. + +The caller is responsible for freeing the list with g_strfreev() when +it is no longer required.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated array of the names of the +actions in the group</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + </parameters> + </method> + <method name="query_action" c:identifier="g_action_group_query_action" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the action exists, else %FALSE</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action in the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="enabled" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">if the action is presently enabled</doc> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + <parameter name="parameter_type" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the parameter type, or %NULL if none needed</doc> + <type name="GLib.VariantType" c:type="const GVariantType**"/> + </parameter> + <parameter name="state_type" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the state type, or %NULL if stateless</doc> + <type name="GLib.VariantType" c:type="const GVariantType**"/> + </parameter> + <parameter name="state_hint" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the state hint, or %NULL if none</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + <parameter name="state" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the current state, or %NULL if stateless</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + </parameters> + </method> + <glib:signal name="action-added" when="last" detailed="1" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action in @action_group</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="action-enabled-changed" when="last" detailed="1" version="2.28"> + <doc xml:space="preserve">Signals that the enabled status of the named action has changed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action in @action_group</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="enabled" transfer-ownership="none"> + <doc xml:space="preserve">whether the action is enabled or not</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="action-removed" when="last" detailed="1" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action in @action_group</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="action-state-changed" when="last" detailed="1" version="2.28"> + <doc xml:space="preserve">Signals that the state of the named action has changed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action in @action_group</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the new value of the state</doc> + <type name="GLib.Variant"/> + </parameter> + </parameters> + </glib:signal> + </interface> + <record name="ActionGroupInterface" c:type="GActionGroupInterface" glib:is-gtype-struct-for="ActionGroup" version="2.28"> + <doc xml:space="preserve">The virtual function table for #GActionGroup.</doc> + <field name="g_iface"> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="has_action"> + <callback name="has_action"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether the named action exists</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to check for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="list_actions"> + <callback name="list_actions"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated array of the names of the +actions in the group</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_action_enabled"> + <callback name="get_action_enabled"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether or not the action is currently enabled</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_action_parameter_type"> + <callback name="get_action_parameter_type"> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the parameter type</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_action_state_type"> + <callback name="get_action_state_type"> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the state type, if the action is stateful</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_action_state_hint"> + <callback name="get_action_state_hint"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the state range hint</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_action_state"> + <callback name="get_action_state"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the current state of the action</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="change_action_state"> + <callback name="change_action_state"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to request the change on</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the new state</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="activate_action"> + <callback name="activate_action"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to activate</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameter" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">parameters to the activation</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="action_added"> + <callback name="action_added"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action in the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="action_removed"> + <callback name="action_removed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action in the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="action_enabled_changed"> + <callback name="action_enabled_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action in the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="enabled" transfer-ownership="none"> + <doc xml:space="preserve">whether or not the action is now enabled</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </callback> + </field> + <field name="action_state_changed"> + <callback name="action_state_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action in the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="state" transfer-ownership="none"> + <doc xml:space="preserve">the new state of the named action</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_action"> + <callback name="query_action"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the action exists, else %FALSE</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action in the group</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="enabled" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">if the action is presently enabled</doc> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + <parameter name="parameter_type" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the parameter type, or %NULL if none needed</doc> + <type name="GLib.VariantType" c:type="const GVariantType**"/> + </parameter> + <parameter name="state_type" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the state type, or %NULL if stateless</doc> + <type name="GLib.VariantType" c:type="const GVariantType**"/> + </parameter> + <parameter name="state_hint" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the state hint, or %NULL if none</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + <parameter name="state" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the current state, or %NULL if stateless</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <record name="ActionInterface" c:type="GActionInterface" glib:is-gtype-struct-for="Action" version="2.28"> + <doc xml:space="preserve">The virtual function table for #GAction.</doc> + <field name="g_iface"> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="get_name"> + <callback name="get_name"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the name of the action</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_parameter_type"> + <callback name="get_parameter_type"> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the parameter type</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_state_type"> + <callback name="get_state_type"> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the state type, if the action is stateful</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_state_hint"> + <callback name="get_state_hint"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the state range hint</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_enabled"> + <callback name="get_enabled"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether the action is enabled</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_state"> + <callback name="get_state"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the current state of the action</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="change_state"> + <callback name="change_state"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the new state</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="activate"> + <callback name="activate"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </parameter> + <parameter name="parameter" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the parameter to the activation</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <interface name="ActionMap" c:symbol-prefix="action_map" c:type="GActionMap" version="2.32" glib:type-name="GActionMap" glib:get-type="g_action_map_get_type" glib:type-struct="ActionMapInterface"> + <doc xml:space="preserve">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.</doc> + <virtual-method name="add_action" invoker="add_action" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_map" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionMap</doc> + <type name="ActionMap" c:type="GActionMap*"/> + </instance-parameter> + <parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_action" invoker="lookup_action" version="2.32"> + <doc xml:space="preserve">Looks up the action with the name @action_name in @action_map. + +If no such action exists, returns %NULL.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a #GAction, or %NULL</doc> + <type name="Action" c:type="GAction*"/> + </return-value> + <parameters> + <instance-parameter name="action_map" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionMap</doc> + <type name="ActionMap" c:type="GActionMap*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="remove_action" invoker="remove_action" version="2.32"> + <doc xml:space="preserve">Removes the named action from the action map. + +If no action of this name is in the map then nothing happens.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_map" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionMap</doc> + <type name="ActionMap" c:type="GActionMap*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <method name="add_action" c:identifier="g_action_map_add_action" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_map" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionMap</doc> + <type name="ActionMap" c:type="GActionMap*"/> + </instance-parameter> + <parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </parameter> + </parameters> + </method> + <method name="add_action_entries" c:identifier="g_action_map_add_action_entries" version="2.32"> + <doc xml:space="preserve">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); +} +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_map" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionMap</doc> + <type name="ActionMap" c:type="GActionMap*"/> + </instance-parameter> + <parameter name="entries" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to + the first item in an array of #GActionEntry structs</doc> + <array length="1" zero-terminated="0" c:type="const GActionEntry*"> + <type name="ActionEntry"/> + </array> + </parameter> + <parameter name="n_entries" transfer-ownership="none"> + <doc xml:space="preserve">the length of @entries, or -1 if @entries is %NULL-terminated</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the user data for signal connections</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="lookup_action" c:identifier="g_action_map_lookup_action" version="2.32"> + <doc xml:space="preserve">Looks up the action with the name @action_name in @action_map. + +If no such action exists, returns %NULL.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a #GAction, or %NULL</doc> + <type name="Action" c:type="GAction*"/> + </return-value> + <parameters> + <instance-parameter name="action_map" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionMap</doc> + <type name="ActionMap" c:type="GActionMap*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="remove_action" c:identifier="g_action_map_remove_action" version="2.32"> + <doc xml:space="preserve">Removes the named action from the action map. + +If no action of this name is in the map then nothing happens.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="action_map" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionMap</doc> + <type name="ActionMap" c:type="GActionMap*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + </interface> + <record name="ActionMapInterface" c:type="GActionMapInterface" glib:is-gtype-struct-for="ActionMap" version="2.32"> + <doc xml:space="preserve">The virtual function table for #GActionMap.</doc> + <field name="g_iface"> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="lookup_action"> + <callback name="lookup_action"> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a #GAction, or %NULL</doc> + <type name="Action" c:type="GAction*"/> + </return-value> + <parameters> + <parameter name="action_map" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionMap</doc> + <type name="ActionMap" c:type="GActionMap*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="add_action"> + <callback name="add_action"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="action_map" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionMap</doc> + <type name="ActionMap" c:type="GActionMap*"/> + </parameter> + <parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="remove_action"> + <callback name="remove_action"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="action_map" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionMap</doc> + <type name="ActionMap" c:type="GActionMap*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <interface name="AppInfo" c:symbol-prefix="app_info" c:type="GAppInfo" glib:type-name="GAppInfo" glib:get-type="g_app_info_get_type" glib:type-struct="AppInfoIface"> + <doc xml:space="preserve">#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.</doc> + <function name="create_from_commandline" c:identifier="g_app_info_create_from_commandline" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">new #GAppInfo for given command.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </return-value> + <parameters> + <parameter name="commandline" transfer-ownership="none"> + <doc xml:space="preserve">the commandline to use</doc> + <type name="filename" c:type="const char*"/> + </parameter> + <parameter name="application_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the application name, or %NULL to use @commandline</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags that can specify details of the created #GAppInfo</doc> + <type name="AppInfoCreateFlags" c:type="GAppInfoCreateFlags"/> + </parameter> + </parameters> + </function> + <function name="get_all" c:identifier="g_app_info_get_all"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated #GList of references to #GAppInfos.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="AppInfo"/> + </type> + </return-value> + </function> + <function name="get_all_for_type" c:identifier="g_app_info_get_all_for_type"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GList of #GAppInfos + for given @content_type or %NULL on error.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="AppInfo"/> + </type> + </return-value> + <parameters> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">the content type to find a #GAppInfo for</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="get_default_for_type" c:identifier="g_app_info_get_default_for_type"> + <doc xml:space="preserve">Gets the default #GAppInfo for a given content type.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">#GAppInfo for given @content_type or + %NULL on error.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </return-value> + <parameters> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">the content type to find a #GAppInfo for</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="must_support_uris" transfer-ownership="none"> + <doc xml:space="preserve">if %TRUE, the #GAppInfo is expected to + support URIs</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="get_default_for_uri_scheme" c:identifier="g_app_info_get_default_for_uri_scheme"> + <doc xml:space="preserve">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".</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">#GAppInfo for given @uri_scheme or + %NULL on error.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </return-value> + <parameters> + <parameter name="uri_scheme" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a URI scheme.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="get_fallback_for_type" c:identifier="g_app_info_get_fallback_for_type" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GList of #GAppInfos + for given @content_type or %NULL on error.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="AppInfo"/> + </type> + </return-value> + <parameters> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">the content type to find a #GAppInfo for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="get_recommended_for_type" c:identifier="g_app_info_get_recommended_for_type" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GList of #GAppInfos + for given @content_type or %NULL on error.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="AppInfo"/> + </type> + </return-value> + <parameters> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">the content type to find a #GAppInfo for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="launch_default_for_uri" c:identifier="g_app_info_launch_default_for_uri" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">the uri to show</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GAppLaunchContext</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + </parameters> + </function> + <function name="launch_default_for_uri_async" c:identifier="g_app_info_launch_default_for_uri_async" version="2.50"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">the uri to show</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GAppLaunchContext</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is done</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="launch_default_for_uri_finish" c:identifier="g_app_info_launch_default_for_uri_finish" version="2.50" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous launch-default-for-uri operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the launch was successful, %FALSE if @error is set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </function> + <function name="reset_type_associations" c:identifier="g_app_info_reset_type_associations" version="2.20"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">a content type</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <virtual-method name="add_supports_type" invoker="add_supports_type" throws="1"> + <doc xml:space="preserve">Adds a content type to the application information to indicate the +application is capable of opening files with the given content type.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">a string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="can_delete" invoker="can_delete" version="2.20"> + <doc xml:space="preserve">Obtains the information whether the #GAppInfo can be deleted. +See g_app_info_delete().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @appinfo can be deleted</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="can_remove_supports_type" invoker="can_remove_supports_type"> + <doc xml:space="preserve">Checks if a supported content type can be removed from an application.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if it is possible to remove supported + content types from a given @appinfo, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="do_delete" invoker="delete" version="2.20"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @appinfo has been deleted</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="dup" invoker="dup"> + <doc xml:space="preserve">Creates a duplicate of a #GAppInfo.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a duplicate of @appinfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="equal" invoker="equal"> + <doc xml:space="preserve">Checks if two #GAppInfos are equal. + +Note that the check *may not* 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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo1" transfer-ownership="none"> + <doc xml:space="preserve">the first #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="appinfo2" transfer-ownership="none"> + <doc xml:space="preserve">the second #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_commandline" invoker="get_commandline" version="2.20"> + <doc xml:space="preserve">Gets the commandline with which the application will be +started.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing the @appinfo's commandline, + or %NULL if this information is not available</doc> + <type name="filename" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_description" invoker="get_description"> + <doc xml:space="preserve">Gets a human-readable description of an installed application.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing a description of the +application @appinfo, or %NULL if none.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_display_name" invoker="get_display_name" version="2.24"> + <doc xml:space="preserve">Gets the display name of the application. The display name is often more +descriptive to the user than the name itself.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the display name of the application for @appinfo, or the name if +no display name is available.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_executable" invoker="get_executable"> + <doc xml:space="preserve">Gets the executable's name for the installed application.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a string containing the @appinfo's application +binaries name</doc> + <type name="filename" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_icon" invoker="get_icon"> + <doc xml:space="preserve">Gets the icon for the application.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the default #GIcon for @appinfo or %NULL +if there is no default icon.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_id" invoker="get_id"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing the application's ID.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_name" invoker="get_name"> + <doc xml:space="preserve">Gets the installed name of the application.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the name of the application for @appinfo.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_supported_types" invoker="get_supported_types" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve"> + a list of content types.</doc> + <array c:type="const char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo that can handle files</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="launch" invoker="launch" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful launch, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="files" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GList of #GFile objects</doc> + <type name="GLib.List" c:type="GList*"> + <type name="File"/> + </type> + </parameter> + <parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GAppLaunchContext or %NULL</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="launch_uris" invoker="launch_uris" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful launch, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="uris" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GList containing URIs to launch.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="utf8"/> + </type> + </parameter> + <parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GAppLaunchContext or %NULL</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="launch_uris_async" invoker="launch_uris_async" version="2.60"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="uris" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GList containing URIs to launch.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="utf8"/> + </type> + </parameter> + <parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GAppLaunchContext or %NULL</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is done</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="launch_uris_finish" invoker="launch_uris_finish" version="2.60" throws="1"> + <doc xml:space="preserve">Finishes a g_app_info_launch_uris_async() operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful launch, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="remove_supports_type" invoker="remove_supports_type" throws="1"> + <doc xml:space="preserve">Removes a supported type from an application, if possible.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">a string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="set_as_default_for_extension" invoker="set_as_default_for_extension" throws="1"> + <doc xml:space="preserve">Sets the application as the default handler for the given file extension.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="extension" transfer-ownership="none"> + <doc xml:space="preserve">a string containing the file extension + (without the dot).</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="set_as_default_for_type" invoker="set_as_default_for_type" throws="1"> + <doc xml:space="preserve">Sets the application as the default handler for a given type.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">the content type.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="set_as_last_used_for_type" invoker="set_as_last_used_for_type" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">the content type.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="should_show" invoker="should_show"> + <doc xml:space="preserve">Checks if the application info should be shown in menus that +list available applications.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @appinfo should be shown, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="supports_files" invoker="supports_files"> + <doc xml:space="preserve">Checks if the application accepts files as arguments.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @appinfo supports files.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="supports_uris" invoker="supports_uris"> + <doc xml:space="preserve">Checks if the application supports reading files and directories from URIs.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @appinfo supports URIs.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="add_supports_type" c:identifier="g_app_info_add_supports_type" throws="1"> + <doc xml:space="preserve">Adds a content type to the application information to indicate the +application is capable of opening files with the given content type.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">a string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="can_delete" c:identifier="g_app_info_can_delete" version="2.20"> + <doc xml:space="preserve">Obtains the information whether the #GAppInfo can be deleted. +See g_app_info_delete().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @appinfo can be deleted</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="can_remove_supports_type" c:identifier="g_app_info_can_remove_supports_type"> + <doc xml:space="preserve">Checks if a supported content type can be removed from an application.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if it is possible to remove supported + content types from a given @appinfo, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="delete" c:identifier="g_app_info_delete" version="2.20"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @appinfo has been deleted</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="dup" c:identifier="g_app_info_dup"> + <doc xml:space="preserve">Creates a duplicate of a #GAppInfo.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a duplicate of @appinfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="equal" c:identifier="g_app_info_equal"> + <doc xml:space="preserve">Checks if two #GAppInfos are equal. + +Note that the check *may not* 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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo1" transfer-ownership="none"> + <doc xml:space="preserve">the first #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="appinfo2" transfer-ownership="none"> + <doc xml:space="preserve">the second #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </method> + <method name="get_commandline" c:identifier="g_app_info_get_commandline" version="2.20"> + <doc xml:space="preserve">Gets the commandline with which the application will be +started.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing the @appinfo's commandline, + or %NULL if this information is not available</doc> + <type name="filename" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_description" c:identifier="g_app_info_get_description"> + <doc xml:space="preserve">Gets a human-readable description of an installed application.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing a description of the +application @appinfo, or %NULL if none.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_display_name" c:identifier="g_app_info_get_display_name" version="2.24"> + <doc xml:space="preserve">Gets the display name of the application. The display name is often more +descriptive to the user than the name itself.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the display name of the application for @appinfo, or the name if +no display name is available.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_executable" c:identifier="g_app_info_get_executable"> + <doc xml:space="preserve">Gets the executable's name for the installed application.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a string containing the @appinfo's application +binaries name</doc> + <type name="filename" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_icon" c:identifier="g_app_info_get_icon"> + <doc xml:space="preserve">Gets the icon for the application.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the default #GIcon for @appinfo or %NULL +if there is no default icon.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_id" c:identifier="g_app_info_get_id"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing the application's ID.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_name" c:identifier="g_app_info_get_name"> + <doc xml:space="preserve">Gets the installed name of the application.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the name of the application for @appinfo.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_supported_types" c:identifier="g_app_info_get_supported_types" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve"> + a list of content types.</doc> + <array c:type="const char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo that can handle files</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="launch" c:identifier="g_app_info_launch" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful launch, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="files" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GList of #GFile objects</doc> + <type name="GLib.List" c:type="GList*"> + <type name="File"/> + </type> + </parameter> + <parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GAppLaunchContext or %NULL</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + </parameters> + </method> + <method name="launch_uris" c:identifier="g_app_info_launch_uris" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful launch, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="uris" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GList containing URIs to launch.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="utf8"/> + </type> + </parameter> + <parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GAppLaunchContext or %NULL</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + </parameters> + </method> + <method name="launch_uris_async" c:identifier="g_app_info_launch_uris_async" version="2.60"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="uris" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GList containing URIs to launch.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="utf8"/> + </type> + </parameter> + <parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GAppLaunchContext or %NULL</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is done</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="launch_uris_finish" c:identifier="g_app_info_launch_uris_finish" version="2.60" throws="1"> + <doc xml:space="preserve">Finishes a g_app_info_launch_uris_async() operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful launch, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="remove_supports_type" c:identifier="g_app_info_remove_supports_type" throws="1"> + <doc xml:space="preserve">Removes a supported type from an application, if possible.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">a string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_as_default_for_extension" c:identifier="g_app_info_set_as_default_for_extension" throws="1"> + <doc xml:space="preserve">Sets the application as the default handler for the given file extension.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="extension" transfer-ownership="none"> + <doc xml:space="preserve">a string containing the file extension + (without the dot).</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_as_default_for_type" c:identifier="g_app_info_set_as_default_for_type" throws="1"> + <doc xml:space="preserve">Sets the application as the default handler for a given type.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">the content type.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_as_last_used_for_type" c:identifier="g_app_info_set_as_last_used_for_type" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">the content type.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="should_show" c:identifier="g_app_info_should_show"> + <doc xml:space="preserve">Checks if the application info should be shown in menus that +list available applications.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @appinfo should be shown, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="supports_files" c:identifier="g_app_info_supports_files"> + <doc xml:space="preserve">Checks if the application accepts files as arguments.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @appinfo supports files.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="supports_uris" c:identifier="g_app_info_supports_uris"> + <doc xml:space="preserve">Checks if the application supports reading files and directories from URIs.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @appinfo supports URIs.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </instance-parameter> + </parameters> + </method> + </interface> + <bitfield name="AppInfoCreateFlags" glib:type-name="GAppInfoCreateFlags" glib:get-type="g_app_info_create_flags_get_type" c:type="GAppInfoCreateFlags"> + <doc xml:space="preserve">Flags used when creating a #GAppInfo.</doc> + <member name="none" value="0" c:identifier="G_APP_INFO_CREATE_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags.</doc> + </member> + <member name="needs_terminal" value="1" c:identifier="G_APP_INFO_CREATE_NEEDS_TERMINAL" glib:nick="needs-terminal"> + <doc xml:space="preserve">Application opens in a terminal window.</doc> + </member> + <member name="supports_uris" value="2" c:identifier="G_APP_INFO_CREATE_SUPPORTS_URIS" glib:nick="supports-uris"> + <doc xml:space="preserve">Application supports URI arguments.</doc> + </member> + <member name="supports_startup_notification" value="4" c:identifier="G_APP_INFO_CREATE_SUPPORTS_STARTUP_NOTIFICATION" glib:nick="supports-startup-notification"> + <doc xml:space="preserve">Application supports startup notification. Since 2.26</doc> + </member> + </bitfield> + <record name="AppInfoIface" c:type="GAppInfoIface" glib:is-gtype-struct-for="AppInfo"> + <doc xml:space="preserve">Application Information interface, for operating system portability.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="dup"> + <callback name="dup"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a duplicate of @appinfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="equal"> + <callback name="equal"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="appinfo1" transfer-ownership="none"> + <doc xml:space="preserve">the first #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="appinfo2" transfer-ownership="none"> + <doc xml:space="preserve">the second #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_id"> + <callback name="get_id"> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing the application's ID.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_name"> + <callback name="get_name"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the name of the application for @appinfo.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_description"> + <callback name="get_description"> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing a description of the +application @appinfo, or %NULL if none.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_executable"> + <callback name="get_executable"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a string containing the @appinfo's application +binaries name</doc> + <type name="filename" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_icon"> + <callback name="get_icon"> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the default #GIcon for @appinfo or %NULL +if there is no default icon.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="launch"> + <callback name="launch" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful launch, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="files" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GList of #GFile objects</doc> + <type name="GLib.List" c:type="GList*"> + <type name="File"/> + </type> + </parameter> + <parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GAppLaunchContext or %NULL</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="supports_uris"> + <callback name="supports_uris"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @appinfo supports URIs.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="supports_files"> + <callback name="supports_files"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @appinfo supports files.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="launch_uris"> + <callback name="launch_uris" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful launch, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="uris" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GList containing URIs to launch.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="utf8"/> + </type> + </parameter> + <parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GAppLaunchContext or %NULL</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="should_show"> + <callback name="should_show"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @appinfo should be shown, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="set_as_default_for_type"> + <callback name="set_as_default_for_type" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">the content type.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="set_as_default_for_extension"> + <callback name="set_as_default_for_extension" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="extension" transfer-ownership="none"> + <doc xml:space="preserve">a string containing the file extension + (without the dot).</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="add_supports_type"> + <callback name="add_supports_type" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">a string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_remove_supports_type"> + <callback name="can_remove_supports_type"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if it is possible to remove supported + content types from a given @appinfo, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="remove_supports_type"> + <callback name="remove_supports_type" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">a string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_delete"> + <callback name="can_delete"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @appinfo can be deleted</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="do_delete"> + <callback name="do_delete"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @appinfo has been deleted</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_commandline"> + <callback name="get_commandline"> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing the @appinfo's commandline, + or %NULL if this information is not available</doc> + <type name="filename" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_display_name"> + <callback name="get_display_name"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the display name of the application for @appinfo, or the name if +no display name is available.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="set_as_last_used_for_type"> + <callback name="set_as_last_used_for_type" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">the content type.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_supported_types"> + <callback name="get_supported_types"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve"> + a list of content types.</doc> + <array c:type="const char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo that can handle files</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="launch_uris_async"> + <callback name="launch_uris_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="uris" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GList containing URIs to launch.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="utf8"/> + </type> + </parameter> + <parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GAppLaunchContext or %NULL</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is done</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="launch_uris_finish"> + <callback name="launch_uris_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful launch, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="AppInfoMonitor" c:symbol-prefix="app_info_monitor" c:type="GAppInfoMonitor" version="2.40" parent="GObject.Object" glib:type-name="GAppInfoMonitor" glib:get-type="g_app_info_monitor_get_type"> + <doc xml:space="preserve">#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.</doc> + <function name="get" c:identifier="g_app_info_monitor_get" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a reference to a #GAppInfoMonitor</doc> + <type name="AppInfoMonitor" c:type="GAppInfoMonitor*"/> + </return-value> + </function> + <glib:signal name="changed" when="first"> + <doc xml:space="preserve">Signal emitted when the app info database for changes (ie: newly installed +or removed applications).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + </class> + <class name="AppLaunchContext" c:symbol-prefix="app_launch_context" c:type="GAppLaunchContext" parent="GObject.Object" glib:type-name="GAppLaunchContext" glib:get-type="g_app_launch_context_get_type" glib:type-struct="AppLaunchContextClass"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_app_launch_context_new"> + <doc xml:space="preserve">Creates a new application launch context. This is not normally used, +instead you instantiate a subclass of this, such as #GdkAppLaunchContext.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GAppLaunchContext.</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </return-value> + </constructor> + <virtual-method name="get_display" invoker="get_display"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a display string for the display.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppLaunchContext</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </instance-parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="files" transfer-ownership="none"> + <doc xml:space="preserve">a #GList of #GFile objects</doc> + <type name="GLib.List" c:type="GList*"> + <type name="File"/> + </type> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_startup_notify_id" invoker="get_startup_notify_id"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a startup notification ID for the application, or %NULL if + not supported.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppLaunchContext</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </instance-parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="files" transfer-ownership="none"> + <doc xml:space="preserve">a #GList of of #GFile objects</doc> + <type name="GLib.List" c:type="GList*"> + <type name="File"/> + </type> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="launch_failed" invoker="launch_failed"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppLaunchContext.</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </instance-parameter> + <parameter name="startup_notify_id" transfer-ownership="none"> + <doc xml:space="preserve">the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="launched"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </instance-parameter> + <parameter name="info" transfer-ownership="none"> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="platform_data" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_display" c:identifier="g_app_launch_context_get_display"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a display string for the display.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppLaunchContext</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </instance-parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="files" transfer-ownership="none"> + <doc xml:space="preserve">a #GList of #GFile objects</doc> + <type name="GLib.List" c:type="GList*"> + <type name="File"/> + </type> + </parameter> + </parameters> + </method> + <method name="get_environment" c:identifier="g_app_launch_context_get_environment" version="2.32"> + <doc xml:space="preserve">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`.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + the child's environment</doc> + <array c:type="char**"> + <type name="filename"/> + </array> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppLaunchContext</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_startup_notify_id" c:identifier="g_app_launch_context_get_startup_notify_id"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a startup notification ID for the application, or %NULL if + not supported.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppLaunchContext</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </instance-parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="files" transfer-ownership="none"> + <doc xml:space="preserve">a #GList of of #GFile objects</doc> + <type name="GLib.List" c:type="GList*"> + <type name="File"/> + </type> + </parameter> + </parameters> + </method> + <method name="launch_failed" c:identifier="g_app_launch_context_launch_failed"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppLaunchContext.</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </instance-parameter> + <parameter name="startup_notify_id" transfer-ownership="none"> + <doc xml:space="preserve">the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="setenv" c:identifier="g_app_launch_context_setenv" version="2.32"> + <doc xml:space="preserve">Arranges for @variable to be set to @value in the child's +environment when @context is used to launch an application.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppLaunchContext</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </instance-parameter> + <parameter name="variable" transfer-ownership="none"> + <doc xml:space="preserve">the environment variable to set</doc> + <type name="filename" c:type="const char*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value for to set the variable to.</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="unsetenv" c:identifier="g_app_launch_context_unsetenv" version="2.32"> + <doc xml:space="preserve">Arranges for @variable to be unset in the child's environment +when @context is used to launch an application.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppLaunchContext</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </instance-parameter> + <parameter name="variable" transfer-ownership="none"> + <doc xml:space="preserve">the environment variable to remove</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="AppLaunchContextPrivate" c:type="GAppLaunchContextPrivate*"/> + </field> + <glib:signal name="launch-failed" when="last" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="startup_notify_id" transfer-ownership="none"> + <doc xml:space="preserve">the startup notification id for the failed launch</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="launched" when="last" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">the #GAppInfo that was just launched</doc> + <type name="AppInfo"/> + </parameter> + <parameter name="platform_data" transfer-ownership="none"> + <doc xml:space="preserve">additional platform-specific data for this launch</doc> + <type name="GLib.Variant"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="AppLaunchContextClass" c:type="GAppLaunchContextClass" glib:is-gtype-struct-for="AppLaunchContext"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="get_display"> + <callback name="get_display"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a display string for the display.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppLaunchContext</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="files" transfer-ownership="none"> + <doc xml:space="preserve">a #GList of #GFile objects</doc> + <type name="GLib.List" c:type="GList*"> + <type name="File"/> + </type> + </parameter> + </parameters> + </callback> + </field> + <field name="get_startup_notify_id"> + <callback name="get_startup_notify_id"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a startup notification ID for the application, or %NULL if + not supported.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppLaunchContext</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppInfo</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="files" transfer-ownership="none"> + <doc xml:space="preserve">a #GList of of #GFile objects</doc> + <type name="GLib.List" c:type="GList*"> + <type name="File"/> + </type> + </parameter> + </parameters> + </callback> + </field> + <field name="launch_failed"> + <callback name="launch_failed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="context" transfer-ownership="none"> + <doc xml:space="preserve">a #GAppLaunchContext.</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + <parameter name="startup_notify_id" transfer-ownership="none"> + <doc xml:space="preserve">the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="launched"> + <callback name="launched"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="context" transfer-ownership="none"> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + <parameter name="info" transfer-ownership="none"> + <type name="AppInfo" c:type="GAppInfo*"/> + </parameter> + <parameter name="platform_data" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="AppLaunchContextPrivate" c:type="GAppLaunchContextPrivate" disguised="1"/> + <class name="Application" c:symbol-prefix="application" c:type="GApplication" version="2.28" parent="GObject.Object" glib:type-name="GApplication" glib:get-type="g_application_get_type" glib:type-struct="ApplicationClass"> + <doc xml:space="preserve">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 +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).</doc> + <implements name="ActionGroup"/> + <implements name="ActionMap"/> + <constructor name="new" c:identifier="g_application_new"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GApplication instance</doc> + <type name="Application" c:type="GApplication*"/> + </return-value> + <parameters> + <parameter name="application_id" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the application id</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">the application flags</doc> + <type name="ApplicationFlags" c:type="GApplicationFlags"/> + </parameter> + </parameters> + </constructor> + <function name="get_default" c:identifier="g_application_get_default" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the default application for this process, or %NULL</doc> + <type name="Application" c:type="GApplication*"/> + </return-value> + </function> + <function name="id_is_valid" c:identifier="g_application_id_is_valid"> + <doc xml:space="preserve">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`.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @application_id is valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="application_id" transfer-ownership="none"> + <doc xml:space="preserve">a potential application identifier</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <virtual-method name="activate" invoker="activate" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="add_platform_data"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="builder" transfer-ownership="none"> + <type name="GLib.VariantBuilder" c:type="GVariantBuilder*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="after_emit"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="platform_data" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="before_emit"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="platform_data" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="command_line"> + <return-value transfer-ownership="none"> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="command_line" transfer-ownership="none"> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="dbus_register" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none"> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="dbus_unregister"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none"> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="handle_local_options"> + <return-value transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="options" transfer-ownership="none"> + <type name="GLib.VariantDict" c:type="GVariantDict*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="local_command_line"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the commandline has been completely handled</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="arguments" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">array of command line arguments</doc> + <array c:type="gchar***"> + <type name="utf8" c:type="gchar**"/> + </array> + </parameter> + <parameter name="exit_status" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">exit status to fill after processing the command line.</doc> + <type name="gint" c:type="int*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="name_lost"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="open" invoker="open" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="files" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GFiles to open</doc> + <array length="1" zero-terminated="0" c:type="GFile**"> + <type name="File" c:type="GFile*"/> + </array> + </parameter> + <parameter name="n_files" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @files array</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="hint" transfer-ownership="none"> + <doc xml:space="preserve">a hint (or ""), but never %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="quit_mainloop"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="run_mainloop"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="shutdown"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="startup"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="activate" c:identifier="g_application_activate" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </method> + <method name="add_main_option" c:identifier="g_application_add_main_option" version="2.42"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">the #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="long_name" transfer-ownership="none"> + <doc xml:space="preserve">the long name of an option used to specify it in a commandline</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="short_name" transfer-ownership="none"> + <doc xml:space="preserve">the short name of an option</doc> + <type name="gchar" c:type="char"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags from #GOptionFlags</doc> + <type name="GLib.OptionFlags" c:type="GOptionFlags"/> + </parameter> + <parameter name="arg" transfer-ownership="none"> + <doc xml:space="preserve">the type of the option, as a #GOptionArg</doc> + <type name="GLib.OptionArg" c:type="GOptionArg"/> + </parameter> + <parameter name="description" transfer-ownership="none"> + <doc xml:space="preserve">the description for the option in `--help` output</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="arg_description" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the placeholder to use for the extra argument + parsed by the option in `--help` output</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="add_main_option_entries" c:identifier="g_application_add_main_option_entries" version="2.40"> + <doc xml:space="preserve">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`</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="entries" transfer-ownership="none"> + <doc xml:space="preserve">a + %NULL-terminated list of #GOptionEntrys</doc> + <array c:type="const GOptionEntry*"> + <type name="GLib.OptionEntry"/> + </array> + </parameter> + </parameters> + </method> + <method name="add_option_group" c:identifier="g_application_add_option_group" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">the #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="group" transfer-ownership="full"> + <doc xml:space="preserve">a #GOptionGroup</doc> + <type name="GLib.OptionGroup" c:type="GOptionGroup*"/> + </parameter> + </parameters> + </method> + <method name="bind_busy_property" c:identifier="g_application_bind_busy_property" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + <parameter name="property" transfer-ownership="none"> + <doc xml:space="preserve">the name of a boolean property of @object</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_application_id" c:identifier="g_application_get_application_id" version="2.28"> + <doc xml:space="preserve">Gets the unique identifier for @application.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the identifier for @application, owned by @application</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_dbus_connection" c:identifier="g_application_get_dbus_connection" version="2.34"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a #GDBusConnection, or %NULL</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_dbus_object_path" c:identifier="g_application_get_dbus_object_path" version="2.34"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the object path, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_flags" c:identifier="g_application_get_flags" version="2.28"> + <doc xml:space="preserve">Gets the flags for @application. + +See #GApplicationFlags.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the flags for @application</doc> + <type name="ApplicationFlags" c:type="GApplicationFlags"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_inactivity_timeout" c:identifier="g_application_get_inactivity_timeout" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the timeout, in milliseconds</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_busy" c:identifier="g_application_get_is_busy" version="2.44"> + <doc xml:space="preserve">Gets the application's current busy state, as set through +g_application_mark_busy() or g_application_bind_busy_property().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @application is currently marked as busy</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_registered" c:identifier="g_application_get_is_registered" version="2.28"> + <doc xml:space="preserve">Checks if @application is registered. + +An application is registered if g_application_register() has been +successfully called.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @application is registered</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_remote" c:identifier="g_application_get_is_remote" version="2.28"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @application is remote</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_resource_base_path" c:identifier="g_application_get_resource_base_path" version="2.42"> + <doc xml:space="preserve">Gets the resource base path of @application. + +See g_application_set_resource_base_path() for more information.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the base resource path, if one is set</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </method> + <method name="hold" c:identifier="g_application_hold"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </method> + <method name="mark_busy" c:identifier="g_application_mark_busy" version="2.38"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </method> + <method name="open" c:identifier="g_application_open" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="files" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GFiles to open</doc> + <array length="1" zero-terminated="0" c:type="GFile**"> + <type name="File" c:type="GFile*"/> + </array> + </parameter> + <parameter name="n_files" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @files array</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="hint" transfer-ownership="none"> + <doc xml:space="preserve">a hint (or ""), but never %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="quit" c:identifier="g_application_quit" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </method> + <method name="register" c:identifier="g_application_register" version="2.28" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if registration succeeded</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="release" c:identifier="g_application_release"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </method> + <method name="run" c:identifier="g_application_run" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the exit status</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="argc" transfer-ownership="none"> + <doc xml:space="preserve">the argc from main() (or 0 if @argv is %NULL)</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="argv" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve"> + the argv from main(), or %NULL</doc> + <array length="0" zero-terminated="0" c:type="char**"> + <type name="filename"/> + </array> + </parameter> + </parameters> + </method> + <method name="send_notification" c:identifier="g_application_send_notification" version="2.40"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="id" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">id of the notification, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="notification" transfer-ownership="none"> + <doc xml:space="preserve">the #GNotification to send</doc> + <type name="Notification" c:type="GNotification*"/> + </parameter> + </parameters> + </method> + <method name="set_action_group" c:identifier="g_application_set_action_group" version="2.28" deprecated="1" deprecated-version="2.32"> + <doc xml:space="preserve">This used to be how actions were associated with a #GApplication. +Now there is #GActionMap for that.</doc> + <doc-deprecated xml:space="preserve">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.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="action_group" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GActionGroup, or %NULL</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </parameter> + </parameters> + </method> + <method name="set_application_id" c:identifier="g_application_set_application_id" version="2.28"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="application_id" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the identifier for @application</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_default" c:identifier="g_application_set_default" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the application to set as default, or %NULL</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_flags" c:identifier="g_application_set_flags" version="2.28"> + <doc xml:space="preserve">Sets the flags for @application. + +The flags can only be modified if @application has not yet been +registered. + +See #GApplicationFlags.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">the flags for @application</doc> + <type name="ApplicationFlags" c:type="GApplicationFlags"/> + </parameter> + </parameters> + </method> + <method name="set_inactivity_timeout" c:identifier="g_application_set_inactivity_timeout" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="inactivity_timeout" transfer-ownership="none"> + <doc xml:space="preserve">the timeout, in milliseconds</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="set_option_context_description" c:identifier="g_application_set_option_context_description" version="2.56"> + <doc xml:space="preserve">Adds a description to the @application option context. + +See g_option_context_set_description() for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">the #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="description" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string to be shown in `--help` output + after the list of options, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_option_context_parameter_string" c:identifier="g_application_set_option_context_parameter_string" version="2.56"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">the #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="parameter_string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string which is displayed + in the first line of `--help` output, after the usage summary `programname [OPTION...]`.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_option_context_summary" c:identifier="g_application_set_option_context_summary" version="2.56"> + <doc xml:space="preserve">Adds a summary to the @application option context. + +See g_option_context_set_summary() for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">the #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="summary" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string to be shown in `--help` output + before the list of options, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_resource_base_path" c:identifier="g_application_set_resource_base_path" version="2.42"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="resource_path" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the resource path to use</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="unbind_busy_property" c:identifier="g_application_unbind_busy_property" version="2.44"> + <doc xml:space="preserve">Destroys a binding between @property and the busy state of +@application that was previously created with +g_application_bind_busy_property().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + <parameter name="property" transfer-ownership="none"> + <doc xml:space="preserve">the name of a boolean property of @object</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="unmark_busy" c:identifier="g_application_unmark_busy" version="2.38"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + </parameters> + </method> + <method name="withdraw_notification" c:identifier="g_application_withdraw_notification" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </instance-parameter> + <parameter name="id" transfer-ownership="none"> + <doc xml:space="preserve">id of a previously sent notification</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <property name="action-group" readable="0" writable="1" transfer-ownership="none"> + <type name="ActionGroup"/> + </property> + <property name="application-id" writable="1" construct="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="flags" writable="1" transfer-ownership="none"> + <type name="ApplicationFlags"/> + </property> + <property name="inactivity-timeout" writable="1" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </property> + <property name="is-busy" version="2.44" transfer-ownership="none"> + <doc xml:space="preserve">Whether the application is currently marked as busy through +g_application_mark_busy() or g_application_bind_busy_property().</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="is-registered" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="is-remote" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="resource-base-path" writable="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <field name="parent_instance" readable="0" private="1"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="ApplicationPrivate" c:type="GApplicationPrivate*"/> + </field> + <glib:signal name="activate" when="last"> + <doc xml:space="preserve">The ::activate signal is emitted on the primary instance when an +activation occurs. See g_application_activate().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + <glib:signal name="command-line" when="last"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">An integer that is set as the exit status for the calling + process. See g_application_command_line_set_exit_status().</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="command_line" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplicationCommandLine representing the + passed commandline</doc> + <type name="ApplicationCommandLine"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="handle-local-options" when="last" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="options" transfer-ownership="none"> + <doc xml:space="preserve">the options dictionary</doc> + <type name="GLib.VariantDict"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="name-lost" when="last" version="2.60"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the signal has been handled</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + </glib:signal> + <glib:signal name="open" when="last"> + <doc xml:space="preserve">The ::open signal is emitted on the primary instance when there are +files to open. See g_application_open() for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="files" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GFiles</doc> + <array length="1" zero-terminated="0" c:type="gpointer"> + <type name="File"/> + </array> + </parameter> + <parameter name="n_files" transfer-ownership="none"> + <doc xml:space="preserve">the length of @files</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="hint" transfer-ownership="none"> + <doc xml:space="preserve">a hint provided by the calling instance</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="shutdown" when="last"> + <doc xml:space="preserve">The ::shutdown signal is emitted only on the registered primary instance +immediately after the main loop terminates.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + <glib:signal name="startup" when="first"> + <doc xml:space="preserve">The ::startup signal is emitted on the primary instance immediately +after registration. See g_application_register().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + </class> + <record name="ApplicationClass" c:type="GApplicationClass" glib:is-gtype-struct-for="Application" version="2.28"> + <doc xml:space="preserve">Virtual function table for #GApplication.</doc> + <field name="parent_class" readable="0" private="1"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="startup"> + <callback name="startup"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="activate"> + <callback name="activate"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="open"> + <callback name="open"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </parameter> + <parameter name="files" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GFiles to open</doc> + <array length="2" zero-terminated="0" c:type="GFile**"> + <type name="File" c:type="GFile*"/> + </array> + </parameter> + <parameter name="n_files" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @files array</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="hint" transfer-ownership="none"> + <doc xml:space="preserve">a hint (or ""), but never %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="command_line"> + <callback name="command_line"> + <return-value transfer-ownership="none"> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </parameter> + <parameter name="command_line" transfer-ownership="none"> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="local_command_line"> + <callback name="local_command_line"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the commandline has been completely handled</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="application" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplication</doc> + <type name="Application" c:type="GApplication*"/> + </parameter> + <parameter name="arguments" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">array of command line arguments</doc> + <array c:type="gchar***"> + <type name="utf8" c:type="gchar**"/> + </array> + </parameter> + <parameter name="exit_status" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">exit status to fill after processing the command line.</doc> + <type name="gint" c:type="int*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="before_emit"> + <callback name="before_emit"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </parameter> + <parameter name="platform_data" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="after_emit"> + <callback name="after_emit"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </parameter> + <parameter name="platform_data" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="add_platform_data"> + <callback name="add_platform_data"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </parameter> + <parameter name="builder" transfer-ownership="none"> + <type name="GLib.VariantBuilder" c:type="GVariantBuilder*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="quit_mainloop"> + <callback name="quit_mainloop"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="run_mainloop"> + <callback name="run_mainloop"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="shutdown"> + <callback name="shutdown"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="dbus_register"> + <callback name="dbus_register" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </parameter> + <parameter name="connection" transfer-ownership="none"> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="dbus_unregister"> + <callback name="dbus_unregister"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </parameter> + <parameter name="connection" transfer-ownership="none"> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="handle_local_options"> + <callback name="handle_local_options"> + <return-value transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </parameter> + <parameter name="options" transfer-ownership="none"> + <type name="GLib.VariantDict" c:type="GVariantDict*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="name_lost"> + <callback name="name_lost"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="application" transfer-ownership="none"> + <type name="Application" c:type="GApplication*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="7"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <class name="ApplicationCommandLine" c:symbol-prefix="application_command_line" c:type="GApplicationCommandLine" parent="GObject.Object" glib:type-name="GApplicationCommandLine" glib:get-type="g_application_command_line_get_type" glib:type-struct="ApplicationCommandLineClass"> + <doc xml:space="preserve">#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)</doc> + <virtual-method name="get_stdin" invoker="get_stdin" version="2.34"> + <doc xml:space="preserve">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 D-Bus 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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GInputStream for stdin</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <instance-parameter name="cmdline" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplicationCommandLine</doc> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="print_literal"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cmdline" transfer-ownership="none"> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </instance-parameter> + <parameter name="message" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="printerr_literal"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cmdline" transfer-ownership="none"> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </instance-parameter> + <parameter name="message" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <method name="create_file_for_arg" c:identifier="g_application_command_line_create_file_for_arg" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="cmdline" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplicationCommandLine</doc> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </instance-parameter> + <parameter name="arg" transfer-ownership="none"> + <doc xml:space="preserve">an argument from @cmdline</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_arguments" c:identifier="g_application_command_line_get_arguments" version="2.28"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + the string array containing the arguments (the argv)</doc> + <array length="0" zero-terminated="0" c:type="gchar**"> + <type name="filename"/> + </array> + </return-value> + <parameters> + <instance-parameter name="cmdline" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplicationCommandLine</doc> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </instance-parameter> + <parameter name="argc" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the length of the arguments array, or %NULL</doc> + <type name="gint" c:type="int*"/> + </parameter> + </parameters> + </method> + <method name="get_cwd" c:identifier="g_application_command_line_get_cwd" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the current directory, or %NULL</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="cmdline" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplicationCommandLine</doc> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_environ" c:identifier="g_application_command_line_get_environ" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve"> + the environment strings, or %NULL if they were not sent</doc> + <array c:type="const gchar* const*"> + <type name="filename"/> + </array> + </return-value> + <parameters> + <instance-parameter name="cmdline" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplicationCommandLine</doc> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_exit_status" c:identifier="g_application_command_line_get_exit_status" version="2.28"> + <doc xml:space="preserve">Gets the exit status of @cmdline. See +g_application_command_line_set_exit_status() for more information.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the exit status</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="cmdline" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplicationCommandLine</doc> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_remote" c:identifier="g_application_command_line_get_is_remote" version="2.28"> + <doc xml:space="preserve">Determines if @cmdline represents a remote invocation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the invocation was remote</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="cmdline" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplicationCommandLine</doc> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_options_dict" c:identifier="g_application_command_line_get_options_dict" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GVariantDict with the options</doc> + <type name="GLib.VariantDict" c:type="GVariantDict*"/> + </return-value> + <parameters> + <instance-parameter name="cmdline" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplicationCommandLine</doc> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_platform_data" c:identifier="g_application_command_line_get_platform_data" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the platform data, or %NULL</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="cmdline" transfer-ownership="none"> + <doc xml:space="preserve">#GApplicationCommandLine</doc> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_stdin" c:identifier="g_application_command_line_get_stdin" version="2.34"> + <doc xml:space="preserve">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 D-Bus 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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GInputStream for stdin</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <instance-parameter name="cmdline" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplicationCommandLine</doc> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </instance-parameter> + </parameters> + </method> + <method name="getenv" c:identifier="g_application_command_line_getenv" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the value of the variable, or %NULL if unset or unsent</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="cmdline" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplicationCommandLine</doc> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the environment variable to get</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="print" c:identifier="g_application_command_line_print" version="2.28" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cmdline" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplicationCommandLine</doc> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </instance-parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a printf-style format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">arguments, as per @format</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="printerr" c:identifier="g_application_command_line_printerr" version="2.28" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cmdline" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplicationCommandLine</doc> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </instance-parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a printf-style format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">arguments, as per @format</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="set_exit_status" c:identifier="g_application_command_line_set_exit_status" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cmdline" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplicationCommandLine</doc> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </instance-parameter> + <parameter name="exit_status" transfer-ownership="none"> + <doc xml:space="preserve">the exit status</doc> + <type name="gint" c:type="int"/> + </parameter> + </parameters> + </method> + <property name="arguments" readable="0" writable="1" construct-only="1" transfer-ownership="none"> + <type name="GLib.Variant"/> + </property> + <property name="is-remote" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="options" readable="0" writable="1" construct-only="1" transfer-ownership="none"> + <type name="GLib.Variant"/> + </property> + <property name="platform-data" readable="0" writable="1" construct-only="1" transfer-ownership="none"> + <type name="GLib.Variant"/> + </property> + <field name="parent_instance" readable="0" private="1"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="ApplicationCommandLinePrivate" c:type="GApplicationCommandLinePrivate*"/> + </field> + </class> + <record name="ApplicationCommandLineClass" c:type="GApplicationCommandLineClass" glib:is-gtype-struct-for="ApplicationCommandLine" version="2.28"> + <doc xml:space="preserve">The #GApplicationCommandLineClass-struct +contains private data only.</doc> + <field name="parent_class" readable="0" private="1"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="print_literal"> + <callback name="print_literal"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="cmdline" transfer-ownership="none"> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </parameter> + <parameter name="message" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="printerr_literal"> + <callback name="printerr_literal"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="cmdline" transfer-ownership="none"> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </parameter> + <parameter name="message" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_stdin"> + <callback name="get_stdin"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GInputStream for stdin</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <parameter name="cmdline" transfer-ownership="none"> + <doc xml:space="preserve">a #GApplicationCommandLine</doc> + <type name="ApplicationCommandLine" c:type="GApplicationCommandLine*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="11"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <record name="ApplicationCommandLinePrivate" c:type="GApplicationCommandLinePrivate" disguised="1"/> + <bitfield name="ApplicationFlags" version="2.28" glib:type-name="GApplicationFlags" glib:get-type="g_application_flags_get_type" c:type="GApplicationFlags"> + <doc xml:space="preserve">Flags used to define the behaviour of a #GApplication.</doc> + <member name="flags_none" value="0" c:identifier="G_APPLICATION_FLAGS_NONE" glib:nick="flags-none"> + <doc xml:space="preserve">Default</doc> + </member> + <member name="is_service" value="1" c:identifier="G_APPLICATION_IS_SERVICE" glib:nick="is-service"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="is_launcher" value="2" c:identifier="G_APPLICATION_IS_LAUNCHER" glib:nick="is-launcher"> + <doc xml:space="preserve">Don't try to become the primary instance.</doc> + </member> + <member name="handles_open" value="4" c:identifier="G_APPLICATION_HANDLES_OPEN" glib:nick="handles-open"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="handles_command_line" value="8" c:identifier="G_APPLICATION_HANDLES_COMMAND_LINE" glib:nick="handles-command-line"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="send_environment" value="16" c:identifier="G_APPLICATION_SEND_ENVIRONMENT" glib:nick="send-environment"> + <doc xml:space="preserve">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().</doc> + </member> + <member name="non_unique" value="32" c:identifier="G_APPLICATION_NON_UNIQUE" glib:nick="non-unique"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="can_override_app_id" value="64" c:identifier="G_APPLICATION_CAN_OVERRIDE_APP_ID" glib:nick="can-override-app-id"> + <doc xml:space="preserve">Allow users to override the + application ID from the command line with `--gapplication-app-id`. + Since: 2.48</doc> + </member> + <member name="allow_replacement" value="128" c:identifier="G_APPLICATION_ALLOW_REPLACEMENT" glib:nick="allow-replacement"> + <doc xml:space="preserve">Allow another instance to take over + the bus name. Since: 2.60</doc> + </member> + <member name="replace" value="256" c:identifier="G_APPLICATION_REPLACE" glib:nick="replace"> + <doc xml:space="preserve">Take over from another instance. This flag is + usually set by passing `--gapplication-replace` on the commandline. + Since: 2.60</doc> + </member> + </bitfield> + <record name="ApplicationPrivate" c:type="GApplicationPrivate" disguised="1"/> + <bitfield name="AskPasswordFlags" glib:type-name="GAskPasswordFlags" glib:get-type="g_ask_password_flags_get_type" c:type="GAskPasswordFlags"> + <doc xml:space="preserve">#GAskPasswordFlags are used to request specific information from the +user, or to notify the user of their choices in an authentication +situation.</doc> + <member name="need_password" value="1" c:identifier="G_ASK_PASSWORD_NEED_PASSWORD" glib:nick="need-password"> + <doc xml:space="preserve">operation requires a password.</doc> + </member> + <member name="need_username" value="2" c:identifier="G_ASK_PASSWORD_NEED_USERNAME" glib:nick="need-username"> + <doc xml:space="preserve">operation requires a username.</doc> + </member> + <member name="need_domain" value="4" c:identifier="G_ASK_PASSWORD_NEED_DOMAIN" glib:nick="need-domain"> + <doc xml:space="preserve">operation requires a domain.</doc> + </member> + <member name="saving_supported" value="8" c:identifier="G_ASK_PASSWORD_SAVING_SUPPORTED" glib:nick="saving-supported"> + <doc xml:space="preserve">operation supports saving settings.</doc> + </member> + <member name="anonymous_supported" value="16" c:identifier="G_ASK_PASSWORD_ANONYMOUS_SUPPORTED" glib:nick="anonymous-supported"> + <doc xml:space="preserve">operation supports anonymous users.</doc> + </member> + <member name="tcrypt" value="32" c:identifier="G_ASK_PASSWORD_TCRYPT" glib:nick="tcrypt"> + <doc xml:space="preserve">operation takes TCRYPT parameters (Since: 2.58)</doc> + </member> + </bitfield> + <interface name="AsyncInitable" c:symbol-prefix="async_initable" c:type="GAsyncInitable" version="2.22" glib:type-name="GAsyncInitable" glib:get-type="g_async_initable_get_type" glib:type-struct="AsyncInitableIface"> + <doc xml:space="preserve">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); + g_task_set_name (task, G_STRFUNC); + + 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; +} +]|</doc> + <function name="new_async" c:identifier="g_async_initable_new_async" version="2.22" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType supporting #GAsyncInitable.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the operation</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the initialization is + finished</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="first_property_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the name of the first property, or %NULL if no + properties</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the value of the first property, followed by other property + value pairs, and ended by %NULL.</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="new_valist_async" c:identifier="g_async_initable_new_valist_async" version="2.22" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType supporting #GAsyncInitable.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="first_property_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the first property, followed by +the value, and other property value pairs, and ended by %NULL.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="var_args" transfer-ownership="none"> + <doc xml:space="preserve">The var args list generated from @first_property_name.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the operation</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the initialization is + finished</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="newv_async" c:identifier="g_async_initable_newv_async" version="2.22" deprecated="1" deprecated-version="2.54"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_object_new_with_properties() and +g_async_initable_init_async() instead. See #GParameter for more information.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType supporting #GAsyncInitable.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_parameters" transfer-ownership="none"> + <doc xml:space="preserve">the number of parameters in @parameters</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="parameters" transfer-ownership="none"> + <doc xml:space="preserve">the parameters to use to construct the object</doc> + <type name="GObject.Parameter" c:type="GParameter*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the operation</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the initialization is + finished</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <virtual-method name="init_async" invoker="init_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="initable" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncInitable.</doc> + <type name="AsyncInitable" c:type="GAsyncInitable*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the operation</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="init_finish" invoker="init_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes asynchronous initialization and returns the result. +See g_async_initable_init_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful. If an error has occurred, this function +will return %FALSE and set @error appropriately if present.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="initable" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncInitable.</doc> + <type name="AsyncInitable" c:type="GAsyncInitable*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <method name="init_async" c:identifier="g_async_initable_init_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="initable" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncInitable.</doc> + <type name="AsyncInitable" c:type="GAsyncInitable*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the operation</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="init_finish" c:identifier="g_async_initable_init_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes asynchronous initialization and returns the result. +See g_async_initable_init_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful. If an error has occurred, this function +will return %FALSE and set @error appropriately if present.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="initable" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncInitable.</doc> + <type name="AsyncInitable" c:type="GAsyncInitable*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="new_finish" c:identifier="g_async_initable_new_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes the async construction for the various g_async_initable_new +calls, returning the created object or %NULL on error.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created #GObject, + or %NULL on error. Free with g_object_unref().</doc> + <type name="GObject.Object" c:type="GObject*"/> + </return-value> + <parameters> + <instance-parameter name="initable" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncInitable from the callback</doc> + <type name="AsyncInitable" c:type="GAsyncInitable*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult from the callback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + </interface> + <record name="AsyncInitableIface" c:type="GAsyncInitableIface" glib:is-gtype-struct-for="AsyncInitable" version="2.22"> + <doc xml:space="preserve">Provides an interface for asynchronous initializing object such that +initialization may fail.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="init_async"> + <callback name="init_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="initable" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncInitable.</doc> + <type name="AsyncInitable" c:type="GAsyncInitable*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the operation</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="init_finish"> + <callback name="init_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful. If an error has occurred, this function +will return %FALSE and set @error appropriately if present.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="initable" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncInitable.</doc> + <type name="AsyncInitable" c:type="GAsyncInitable*"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <callback name="AsyncReadyCallback" c:type="GAsyncReadyCallback"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="source_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the object the asynchronous operation was started with.</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">user data passed to the callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <interface name="AsyncResult" c:symbol-prefix="async_result" c:type="GAsyncResult" glib:type-name="GAsyncResult" glib:get-type="g_async_result_get_type" glib:type-struct="AsyncResultIface"> + <doc xml:space="preserve">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.</doc> + <virtual-method name="get_source_object" invoker="get_source_object"> + <doc xml:space="preserve">Gets the source object from a #GAsyncResult.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new reference to the source + object for the @res, or %NULL if there is none.</doc> + <type name="GObject.Object" c:type="GObject*"/> + </return-value> + <parameters> + <instance-parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_user_data" invoker="get_user_data"> + <doc xml:space="preserve">Gets the user data from a #GAsyncResult.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the user data for @res.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="is_tagged" invoker="is_tagged" version="2.34"> + <doc xml:space="preserve">Checks if @res has the given @source_tag (generally a function +pointer indicating the function @res was created by).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @res has the indicated @source_tag, %FALSE if + not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </instance-parameter> + <parameter name="source_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an application-defined tag</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_source_object" c:identifier="g_async_result_get_source_object"> + <doc xml:space="preserve">Gets the source object from a #GAsyncResult.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new reference to the source + object for the @res, or %NULL if there is none.</doc> + <type name="GObject.Object" c:type="GObject*"/> + </return-value> + <parameters> + <instance-parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_user_data" c:identifier="g_async_result_get_user_data"> + <doc xml:space="preserve">Gets the user data from a #GAsyncResult.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the user data for @res.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_tagged" c:identifier="g_async_result_is_tagged" version="2.34"> + <doc xml:space="preserve">Checks if @res has the given @source_tag (generally a function +pointer indicating the function @res was created by).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @res has the indicated @source_tag, %FALSE if + not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </instance-parameter> + <parameter name="source_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an application-defined tag</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="legacy_propagate_error" c:identifier="g_async_result_legacy_propagate_error" version="2.34" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @error is has been filled in with an error from + @res, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </instance-parameter> + </parameters> + </method> + </interface> + <record name="AsyncResultIface" c:type="GAsyncResultIface" glib:is-gtype-struct-for="AsyncResult"> + <doc xml:space="preserve">Interface definition for #GAsyncResult.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="get_user_data"> + <callback name="get_user_data"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the user data for @res.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_source_object"> + <callback name="get_source_object"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new reference to the source + object for the @res, or %NULL if there is none.</doc> + <type name="GObject.Object" c:type="GObject*"/> + </return-value> + <parameters> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="is_tagged"> + <callback name="is_tagged"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @res has the indicated @source_tag, %FALSE if + not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="source_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an application-defined tag</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <function-macro name="BUFFERED_INPUT_STREAM" c:identifier="G_BUFFERED_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="BUFFERED_INPUT_STREAM_CLASS" c:identifier="G_BUFFERED_INPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="BUFFERED_INPUT_STREAM_GET_CLASS" c:identifier="G_BUFFERED_INPUT_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="BUFFERED_OUTPUT_STREAM" c:identifier="G_BUFFERED_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="BUFFERED_OUTPUT_STREAM_CLASS" c:identifier="G_BUFFERED_OUTPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="BUFFERED_OUTPUT_STREAM_GET_CLASS" c:identifier="G_BUFFERED_OUTPUT_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="BYTES_ICON" c:identifier="G_BYTES_ICON" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <class name="BufferedInputStream" c:symbol-prefix="buffered_input_stream" c:type="GBufferedInputStream" parent="FilterInputStream" glib:type-name="GBufferedInputStream" glib:get-type="g_buffered_input_stream_get_type" glib:type-struct="BufferedInputStreamClass"> + <doc xml:space="preserve">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.</doc> + <implements name="Seekable"/> + <constructor name="new" c:identifier="g_buffered_input_stream_new"> + <doc xml:space="preserve">Creates a new #GInputStream from the given @base_stream, with +a buffer set to the default size (4 kilobytes).</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GInputStream for the given @base_stream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <parameter name="base_stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_sized" c:identifier="g_buffered_input_stream_new_sized"> + <doc xml:space="preserve">Creates a new #GBufferedInputStream from the given @base_stream, +with a buffer set to @size.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <parameter name="base_stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">a #gsize</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </constructor> + <virtual-method name="fill" invoker="fill" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes read into @stream's buffer, up to @count, + or -1 on error.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedInputStream</doc> + <type name="BufferedInputStream" c:type="GBufferedInputStream*"/> + </instance-parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes that will be read from the stream</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="fill_async" invoker="fill_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedInputStream</doc> + <type name="BufferedInputStream" c:type="GBufferedInputStream*"/> + </instance-parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes that will be read from the stream</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">a #gpointer</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="fill_finish" invoker="fill_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous read.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #gssize of the read stream, or `-1` on an error.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedInputStream</doc> + <type name="BufferedInputStream" c:type="GBufferedInputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <method name="fill" c:identifier="g_buffered_input_stream_fill" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes read into @stream's buffer, up to @count, + or -1 on error.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedInputStream</doc> + <type name="BufferedInputStream" c:type="GBufferedInputStream*"/> + </instance-parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes that will be read from the stream</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="fill_async" c:identifier="g_buffered_input_stream_fill_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedInputStream</doc> + <type name="BufferedInputStream" c:type="GBufferedInputStream*"/> + </instance-parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes that will be read from the stream</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #gpointer</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="fill_finish" c:identifier="g_buffered_input_stream_fill_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous read.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #gssize of the read stream, or `-1` on an error.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedInputStream</doc> + <type name="BufferedInputStream" c:type="GBufferedInputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="get_available" c:identifier="g_buffered_input_stream_get_available"> + <doc xml:space="preserve">Gets the size of the available data within the stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">size of the available stream.</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">#GBufferedInputStream</doc> + <type name="BufferedInputStream" c:type="GBufferedInputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_buffer_size" c:identifier="g_buffered_input_stream_get_buffer_size"> + <doc xml:space="preserve">Gets the size of the input buffer.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the current buffer size.</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedInputStream</doc> + <type name="BufferedInputStream" c:type="GBufferedInputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="peek" c:identifier="g_buffered_input_stream_peek"> + <doc xml:space="preserve">Peeks in the buffer, copying data of size @count into @buffer, +offset @offset bytes.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #gsize of the number of bytes peeked, or -1 on error.</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedInputStream</doc> + <type name="BufferedInputStream" c:type="GBufferedInputStream*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to + an allocated chunk of memory</doc> + <array length="2" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="offset" transfer-ownership="none"> + <doc xml:space="preserve">a #gsize</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">a #gsize</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <method name="peek_buffer" c:identifier="g_buffered_input_stream_peek_buffer"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve"> + read-only buffer</doc> + <array length="0" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedInputStream</doc> + <type name="BufferedInputStream" c:type="GBufferedInputStream*"/> + </instance-parameter> + <parameter name="count" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">a #gsize to get the number of bytes available in the buffer</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="read_byte" c:identifier="g_buffered_input_stream_read_byte" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the byte read from the @stream, or -1 on end of stream or error.</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedInputStream</doc> + <type name="BufferedInputStream" c:type="GBufferedInputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_buffer_size" c:identifier="g_buffered_input_stream_set_buffer_size"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedInputStream</doc> + <type name="BufferedInputStream" c:type="GBufferedInputStream*"/> + </instance-parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">a #gsize</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <property name="buffer-size" writable="1" construct="1" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </property> + <field name="parent_instance"> + <type name="FilterInputStream" c:type="GFilterInputStream"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="BufferedInputStreamPrivate" c:type="GBufferedInputStreamPrivate*"/> + </field> + </class> + <record name="BufferedInputStreamClass" c:type="GBufferedInputStreamClass" glib:is-gtype-struct-for="BufferedInputStream"> + <field name="parent_class"> + <type name="FilterInputStreamClass" c:type="GFilterInputStreamClass"/> + </field> + <field name="fill"> + <callback name="fill" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes read into @stream's buffer, up to @count, + or -1 on error.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedInputStream</doc> + <type name="BufferedInputStream" c:type="GBufferedInputStream*"/> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes that will be read from the stream</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="fill_async"> + <callback name="fill_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedInputStream</doc> + <type name="BufferedInputStream" c:type="GBufferedInputStream*"/> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes that will be read from the stream</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">a #gpointer</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="fill_finish"> + <callback name="fill_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #gssize of the read stream, or `-1` on an error.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedInputStream</doc> + <type name="BufferedInputStream" c:type="GBufferedInputStream*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="BufferedInputStreamPrivate" c:type="GBufferedInputStreamPrivate" disguised="1"/> + <class name="BufferedOutputStream" c:symbol-prefix="buffered_output_stream" c:type="GBufferedOutputStream" parent="FilterOutputStream" glib:type-name="GBufferedOutputStream" glib:get-type="g_buffered_output_stream_get_type" glib:type-struct="BufferedOutputStreamClass"> + <doc xml:space="preserve">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.</doc> + <implements name="Seekable"/> + <constructor name="new" c:identifier="g_buffered_output_stream_new"> + <doc xml:space="preserve">Creates a new buffered output stream for a base stream.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GOutputStream for the given @base_stream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </return-value> + <parameters> + <parameter name="base_stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_sized" c:identifier="g_buffered_output_stream_new_sized"> + <doc xml:space="preserve">Creates a new buffered output stream with a given buffer size.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GOutputStream with an internal buffer set to @size.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </return-value> + <parameters> + <parameter name="base_stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">a #gsize.</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </constructor> + <method name="get_auto_grow" c:identifier="g_buffered_output_stream_get_auto_grow"> + <doc xml:space="preserve">Checks if the buffer automatically grows as data is added.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @stream's buffer automatically grows, +%FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedOutputStream.</doc> + <type name="BufferedOutputStream" c:type="GBufferedOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_buffer_size" c:identifier="g_buffered_output_stream_get_buffer_size"> + <doc xml:space="preserve">Gets the size of the buffer in the @stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the current size of the buffer.</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedOutputStream.</doc> + <type name="BufferedOutputStream" c:type="GBufferedOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_auto_grow" c:identifier="g_buffered_output_stream_set_auto_grow"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedOutputStream.</doc> + <type name="BufferedOutputStream" c:type="GBufferedOutputStream*"/> + </instance-parameter> + <parameter name="auto_grow" transfer-ownership="none"> + <doc xml:space="preserve">a #gboolean.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_buffer_size" c:identifier="g_buffered_output_stream_set_buffer_size"> + <doc xml:space="preserve">Sets the size of the internal buffer to @size.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GBufferedOutputStream.</doc> + <type name="BufferedOutputStream" c:type="GBufferedOutputStream*"/> + </instance-parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">a #gsize.</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <property name="auto-grow" writable="1" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="buffer-size" writable="1" construct="1" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </property> + <field name="parent_instance"> + <type name="FilterOutputStream" c:type="GFilterOutputStream"/> + </field> + <field name="priv"> + <type name="BufferedOutputStreamPrivate" c:type="GBufferedOutputStreamPrivate*"/> + </field> + </class> + <record name="BufferedOutputStreamClass" c:type="GBufferedOutputStreamClass" glib:is-gtype-struct-for="BufferedOutputStream"> + <field name="parent_class"> + <type name="FilterOutputStreamClass" c:type="GFilterOutputStreamClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="BufferedOutputStreamPrivate" c:type="GBufferedOutputStreamPrivate" disguised="1"/> + <callback name="BusAcquiredCallback" c:type="GBusAcquiredCallback" version="2.26"> + <doc xml:space="preserve">Invoked when a connection to a message bus has been obtained.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusConnection to a message bus.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">The name that is requested to be owned.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">User data passed to g_bus_own_name().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="BusNameAcquiredCallback" c:type="GBusNameAcquiredCallback" version="2.26"> + <doc xml:space="preserve">Invoked when the name is acquired.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusConnection on which to acquired the name.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">The name being owned.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">User data passed to g_bus_own_name() or g_bus_own_name_on_connection().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="BusNameAppearedCallback" c:type="GBusNameAppearedCallback" version="2.26"> + <doc xml:space="preserve">Invoked when the name being watched is known to have to have an owner.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusConnection the name is being watched on.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">The name being watched.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="name_owner" transfer-ownership="none"> + <doc xml:space="preserve">Unique name of the owner of the name being watched.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">User data passed to g_bus_watch_name().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="BusNameLostCallback" c:type="GBusNameLostCallback" version="2.26"> + <doc xml:space="preserve">Invoked when the name is lost or @connection has been closed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusConnection on which to acquire the name or %NULL if +the connection was disconnected.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">The name being owned.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">User data passed to g_bus_own_name() or g_bus_own_name_on_connection().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <bitfield name="BusNameOwnerFlags" version="2.26" glib:type-name="GBusNameOwnerFlags" glib:get-type="g_bus_name_owner_flags_get_type" c:type="GBusNameOwnerFlags"> + <doc xml:space="preserve">Flags used in g_bus_own_name().</doc> + <member name="none" value="0" c:identifier="G_BUS_NAME_OWNER_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="allow_replacement" value="1" c:identifier="G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT" glib:nick="allow-replacement"> + <doc xml:space="preserve">Allow another message bus connection to claim the name.</doc> + </member> + <member name="replace" value="2" c:identifier="G_BUS_NAME_OWNER_FLAGS_REPLACE" glib:nick="replace"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="do_not_queue" value="4" c:identifier="G_BUS_NAME_OWNER_FLAGS_DO_NOT_QUEUE" glib:nick="do-not-queue"> + <doc xml:space="preserve">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)</doc> + </member> + </bitfield> + <callback name="BusNameVanishedCallback" c:type="GBusNameVanishedCallback" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusConnection the name is being watched on, or + %NULL.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">The name being watched.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">User data passed to g_bus_watch_name().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <bitfield name="BusNameWatcherFlags" version="2.26" glib:type-name="GBusNameWatcherFlags" glib:get-type="g_bus_name_watcher_flags_get_type" c:type="GBusNameWatcherFlags"> + <doc xml:space="preserve">Flags used in g_bus_watch_name().</doc> + <member name="none" value="0" c:identifier="G_BUS_NAME_WATCHER_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="auto_start" value="1" c:identifier="G_BUS_NAME_WATCHER_FLAGS_AUTO_START" glib:nick="auto-start"> + <doc xml:space="preserve">If no-one owns the name when +beginning to watch the name, ask the bus to launch an owner for the +name.</doc> + </member> + </bitfield> + <enumeration name="BusType" version="2.26" glib:type-name="GBusType" glib:get-type="g_bus_type_get_type" c:type="GBusType"> + <doc xml:space="preserve">An enumeration for well-known message buses.</doc> + <member name="starter" value="-1" c:identifier="G_BUS_TYPE_STARTER" glib:nick="starter"> + <doc xml:space="preserve">An alias for the message bus that activated the process, if any.</doc> + </member> + <member name="none" value="0" c:identifier="G_BUS_TYPE_NONE" glib:nick="none"> + <doc xml:space="preserve">Not a message bus.</doc> + </member> + <member name="system" value="1" c:identifier="G_BUS_TYPE_SYSTEM" glib:nick="system"> + <doc xml:space="preserve">The system-wide message bus.</doc> + </member> + <member name="session" value="2" c:identifier="G_BUS_TYPE_SESSION" glib:nick="session"> + <doc xml:space="preserve">The login session message bus.</doc> + </member> + </enumeration> + <class name="BytesIcon" c:symbol-prefix="bytes_icon" c:type="GBytesIcon" version="2.38" parent="GObject.Object" glib:type-name="GBytesIcon" glib:get-type="g_bytes_icon_get_type"> + <doc xml:space="preserve">#GBytesIcon specifies an image held in memory in a common format (usually +png) to be used as icon.</doc> + <implements name="Icon"/> + <implements name="LoadableIcon"/> + <constructor name="new" c:identifier="g_bytes_icon_new" version="2.38"> + <doc xml:space="preserve">Creates a new icon for a bytes. + +This cannot fail, but loading and interpreting the bytes may fail later on +(for example, if g_loadable_icon_load() is called) if the image is invalid.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon for the given + @bytes.</doc> + <type name="BytesIcon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="bytes" transfer-ownership="none"> + <doc xml:space="preserve">a #GBytes.</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + </parameters> + </constructor> + <method name="get_bytes" c:identifier="g_bytes_icon_get_bytes" version="2.38"> + <doc xml:space="preserve">Gets the #GBytes associated with the given @icon.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GBytes.</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <instance-parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GIcon.</doc> + <type name="BytesIcon" c:type="GBytesIcon*"/> + </instance-parameter> + </parameters> + </method> + <property name="bytes" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The bytes containing the icon.</doc> + <type name="GLib.Bytes"/> + </property> + </class> + <function-macro name="CANCELLABLE" c:identifier="G_CANCELLABLE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CANCELLABLE_CLASS" c:identifier="G_CANCELLABLE_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CANCELLABLE_GET_CLASS" c:identifier="G_CANCELLABLE_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CHARSET_CONVERTER" c:identifier="G_CHARSET_CONVERTER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CHARSET_CONVERTER_CLASS" c:identifier="G_CHARSET_CONVERTER_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CHARSET_CONVERTER_GET_CLASS" c:identifier="G_CHARSET_CONVERTER_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CONVERTER" c:identifier="G_CONVERTER" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CONVERTER_GET_IFACE" c:identifier="G_CONVERTER_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CONVERTER_INPUT_STREAM" c:identifier="G_CONVERTER_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CONVERTER_INPUT_STREAM_CLASS" c:identifier="G_CONVERTER_INPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CONVERTER_INPUT_STREAM_GET_CLASS" c:identifier="G_CONVERTER_INPUT_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CONVERTER_OUTPUT_STREAM" c:identifier="G_CONVERTER_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CONVERTER_OUTPUT_STREAM_CLASS" c:identifier="G_CONVERTER_OUTPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CONVERTER_OUTPUT_STREAM_GET_CLASS" c:identifier="G_CONVERTER_OUTPUT_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CREDENTIALS" c:identifier="G_CREDENTIALS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CREDENTIALS_CLASS" c:identifier="G_CREDENTIALS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CREDENTIALS_GET_CLASS" c:identifier="G_CREDENTIALS_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <class name="Cancellable" c:symbol-prefix="cancellable" c:type="GCancellable" parent="GObject.Object" glib:type-name="GCancellable" glib:get-type="g_cancellable_get_type" glib:type-struct="CancellableClass"> + <doc xml:space="preserve">GCancellable is a thread-safe operation cancellation stack used +throughout GIO to allow for cancellation of synchronous and +asynchronous operations.</doc> + <constructor name="new" c:identifier="g_cancellable_new"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GCancellable.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </return-value> + </constructor> + <function name="get_current" c:identifier="g_cancellable_get_current"> + <doc xml:space="preserve">Gets the top cancellable from the stack.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a #GCancellable from the top +of the stack, or %NULL if the stack is empty.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </return-value> + </function> + <virtual-method name="cancelled"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="cancel" c:identifier="g_cancellable_cancel"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable object.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </instance-parameter> + </parameters> + </method> + <method name="connect" c:identifier="g_cancellable_connect" version="2.22"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The id of the signal handler or 0 if @cancellable has already + been cancelled.</doc> + <type name="gulong" c:type="gulong"/> + </return-value> + <parameters> + <instance-parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </instance-parameter> + <parameter name="callback" transfer-ownership="none" scope="notified" closure="1" destroy="2"> + <doc xml:space="preserve">The #GCallback to connect.</doc> + <type name="GObject.Callback" c:type="GCallback"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Data to pass to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="data_destroy_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">Free function for @data or %NULL.</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="disconnect" c:identifier="g_cancellable_disconnect" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </instance-parameter> + <parameter name="handler_id" transfer-ownership="none"> + <doc xml:space="preserve">Handler id of the handler to be disconnected, or `0`.</doc> + <type name="gulong" c:type="gulong"/> + </parameter> + </parameters> + </method> + <method name="get_fd" c:identifier="g_cancellable_get_fd"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A valid file descriptor. `-1` if the file descriptor +is not supported, or on errors.</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_cancelled" c:identifier="g_cancellable_is_cancelled"> + <doc xml:space="preserve">Checks if a cancellable job has been cancelled.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @cancellable is cancelled, +FALSE if called with %NULL or if item is not cancelled.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </instance-parameter> + </parameters> + </method> + <method name="make_pollfd" c:identifier="g_cancellable_make_pollfd" version="2.22"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @pollfd was successfully initialized, %FALSE on + failure to prepare the cancellable.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </instance-parameter> + <parameter name="pollfd" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a #GPollFD</doc> + <type name="GLib.PollFD" c:type="GPollFD*"/> + </parameter> + </parameters> + </method> + <method name="pop_current" c:identifier="g_cancellable_pop_current"> + <doc xml:space="preserve">Pops @cancellable off the cancellable stack (verifying that @cancellable +is on the top of the stack).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </instance-parameter> + </parameters> + </method> + <method name="push_current" c:identifier="g_cancellable_push_current"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </instance-parameter> + </parameters> + </method> + <method name="release_fd" c:identifier="g_cancellable_release_fd" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </instance-parameter> + </parameters> + </method> + <method name="reset" c:identifier="g_cancellable_reset"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable object.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_error_if_cancelled" c:identifier="g_cancellable_set_error_if_cancelled" throws="1"> + <doc xml:space="preserve">If the @cancellable is cancelled, sets the error to notify +that the operation was cancelled.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @cancellable was cancelled, %FALSE if it was not</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </instance-parameter> + </parameters> + </method> + <method name="source_new" c:identifier="g_cancellable_source_new" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new #GSource.</doc> + <type name="GLib.Source" c:type="GSource*"/> + </return-value> + <parameters> + <instance-parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </instance-parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="CancellablePrivate" c:type="GCancellablePrivate*"/> + </field> + <glib:signal name="cancelled" when="last"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + </class> + <record name="CancellableClass" c:type="GCancellableClass" glib:is-gtype-struct-for="Cancellable"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="cancelled"> + <callback name="cancelled"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="CancellablePrivate" c:type="GCancellablePrivate" disguised="1"/> + <callback name="CancellableSourceFunc" c:type="GCancellableSourceFunc" version="2.28"> + <doc xml:space="preserve">This is the function type of the callback used for the #GSource +returned by g_cancellable_source_new().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">it should return %FALSE if the source should be removed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="1"> + <doc xml:space="preserve">data passed in by the user.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <class name="CharsetConverter" c:symbol-prefix="charset_converter" c:type="GCharsetConverter" parent="GObject.Object" glib:type-name="GCharsetConverter" glib:get-type="g_charset_converter_get_type" glib:type-struct="CharsetConverterClass"> + <doc xml:space="preserve">#GCharsetConverter is an implementation of #GConverter based on +GIConv.</doc> + <implements name="Converter"/> + <implements name="Initable"/> + <constructor name="new" c:identifier="g_charset_converter_new" version="2.24" throws="1"> + <doc xml:space="preserve">Creates a new #GCharsetConverter.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GCharsetConverter or %NULL on error.</doc> + <type name="CharsetConverter" c:type="GCharsetConverter*"/> + </return-value> + <parameters> + <parameter name="to_charset" transfer-ownership="none"> + <doc xml:space="preserve">destination charset</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="from_charset" transfer-ownership="none"> + <doc xml:space="preserve">source charset</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <method name="get_num_fallbacks" c:identifier="g_charset_converter_get_num_fallbacks" version="2.24"> + <doc xml:space="preserve">Gets the number of fallbacks that @converter has applied so far.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of fallbacks that @converter has applied</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="converter" transfer-ownership="none"> + <doc xml:space="preserve">a #GCharsetConverter</doc> + <type name="CharsetConverter" c:type="GCharsetConverter*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_use_fallback" c:identifier="g_charset_converter_get_use_fallback" version="2.24"> + <doc xml:space="preserve">Gets the #GCharsetConverter:use-fallback property.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if fallbacks are used by @converter</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="converter" transfer-ownership="none"> + <doc xml:space="preserve">a #GCharsetConverter</doc> + <type name="CharsetConverter" c:type="GCharsetConverter*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_use_fallback" c:identifier="g_charset_converter_set_use_fallback" version="2.24"> + <doc xml:space="preserve">Sets the #GCharsetConverter:use-fallback property.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="converter" transfer-ownership="none"> + <doc xml:space="preserve">a #GCharsetConverter</doc> + <type name="CharsetConverter" c:type="GCharsetConverter*"/> + </instance-parameter> + <parameter name="use_fallback" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to use fallbacks</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <property name="from-charset" writable="1" construct-only="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="to-charset" writable="1" construct-only="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="use-fallback" writable="1" construct="1" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </property> + </class> + <record name="CharsetConverterClass" c:type="GCharsetConverterClass" glib:is-gtype-struct-for="CharsetConverter"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <interface name="Converter" c:symbol-prefix="converter" c:type="GConverter" version="2.24" glib:type-name="GConverter" glib:get-type="g_converter_get_type" glib:type-struct="ConverterIface"> + <doc xml:space="preserve">#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.</doc> + <virtual-method name="convert" invoker="convert" version="2.24" throws="1"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GConverterResult, %G_CONVERTER_ERROR on error.</doc> + <type name="ConverterResult" c:type="GConverterResult"/> + </return-value> + <parameters> + <instance-parameter name="converter" transfer-ownership="none"> + <doc xml:space="preserve">a #GConverter.</doc> + <type name="Converter" c:type="GConverter*"/> + </instance-parameter> + <parameter name="inbuf" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the buffer + containing the data to convert.</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="inbuf_size" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes in @inbuf</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="outbuf" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a buffer to write + converted data in.</doc> + <array length="3" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="outbuf_size" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes in @outbuf, must be at least one</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a #GConverterFlags controlling the conversion details</doc> + <type name="ConverterFlags" c:type="GConverterFlags"/> + </parameter> + <parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">will be set to the number of bytes read from @inbuf on success</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">will be set to the number of bytes written to @outbuf on success</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="reset" invoker="reset" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="converter" transfer-ownership="none"> + <doc xml:space="preserve">a #GConverter.</doc> + <type name="Converter" c:type="GConverter*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="convert" c:identifier="g_converter_convert" version="2.24" throws="1"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GConverterResult, %G_CONVERTER_ERROR on error.</doc> + <type name="ConverterResult" c:type="GConverterResult"/> + </return-value> + <parameters> + <instance-parameter name="converter" transfer-ownership="none"> + <doc xml:space="preserve">a #GConverter.</doc> + <type name="Converter" c:type="GConverter*"/> + </instance-parameter> + <parameter name="inbuf" transfer-ownership="none"> + <doc xml:space="preserve">the buffer + containing the data to convert.</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="inbuf_size" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes in @inbuf</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="outbuf" transfer-ownership="none"> + <doc xml:space="preserve">a buffer to write + converted data in.</doc> + <array length="3" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="outbuf_size" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes in @outbuf, must be at least one</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a #GConverterFlags controlling the conversion details</doc> + <type name="ConverterFlags" c:type="GConverterFlags"/> + </parameter> + <parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">will be set to the number of bytes read from @inbuf on success</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">will be set to the number of bytes written to @outbuf on success</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="reset" c:identifier="g_converter_reset" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="converter" transfer-ownership="none"> + <doc xml:space="preserve">a #GConverter.</doc> + <type name="Converter" c:type="GConverter*"/> + </instance-parameter> + </parameters> + </method> + </interface> + <bitfield name="ConverterFlags" version="2.24" glib:type-name="GConverterFlags" glib:get-type="g_converter_flags_get_type" c:type="GConverterFlags"> + <doc xml:space="preserve">Flags used when calling a g_converter_convert().</doc> + <member name="none" value="0" c:identifier="G_CONVERTER_NO_FLAGS" glib:nick="none"> + <doc xml:space="preserve">No flags.</doc> + </member> + <member name="input_at_end" value="1" c:identifier="G_CONVERTER_INPUT_AT_END" glib:nick="input-at-end"> + <doc xml:space="preserve">At end of input data</doc> + </member> + <member name="flush" value="2" c:identifier="G_CONVERTER_FLUSH" glib:nick="flush"> + <doc xml:space="preserve">Flush data</doc> + </member> + </bitfield> + <record name="ConverterIface" c:type="GConverterIface" glib:is-gtype-struct-for="Converter" version="2.24"> + <doc xml:space="preserve">Provides an interface for converting data from one type +to another type. The conversion can be stateful +and may fail at any place.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="convert"> + <callback name="convert" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GConverterResult, %G_CONVERTER_ERROR on error.</doc> + <type name="ConverterResult" c:type="GConverterResult"/> + </return-value> + <parameters> + <parameter name="converter" transfer-ownership="none"> + <doc xml:space="preserve">a #GConverter.</doc> + <type name="Converter" c:type="GConverter*"/> + </parameter> + <parameter name="inbuf" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the buffer + containing the data to convert.</doc> + <array length="2" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="inbuf_size" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes in @inbuf</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="outbuf" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a buffer to write + converted data in.</doc> + <array length="4" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="outbuf_size" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes in @outbuf, must be at least one</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a #GConverterFlags controlling the conversion details</doc> + <type name="ConverterFlags" c:type="GConverterFlags"/> + </parameter> + <parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">will be set to the number of bytes read from @inbuf on success</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">will be set to the number of bytes written to @outbuf on success</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="reset"> + <callback name="reset"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="converter" transfer-ownership="none"> + <doc xml:space="preserve">a #GConverter.</doc> + <type name="Converter" c:type="GConverter*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="ConverterInputStream" c:symbol-prefix="converter_input_stream" c:type="GConverterInputStream" parent="FilterInputStream" glib:type-name="GConverterInputStream" glib:get-type="g_converter_input_stream_get_type" glib:type-struct="ConverterInputStreamClass"> + <doc xml:space="preserve">Converter input stream implements #GInputStream and allows +conversion of data of various types during reading. + +As of GLib 2.34, #GConverterInputStream implements +#GPollableInputStream.</doc> + <implements name="PollableInputStream"/> + <constructor name="new" c:identifier="g_converter_input_stream_new"> + <doc xml:space="preserve">Creates a new converter input stream for the @base_stream.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <parameter name="base_stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="converter" transfer-ownership="none"> + <doc xml:space="preserve">a #GConverter</doc> + <type name="Converter" c:type="GConverter*"/> + </parameter> + </parameters> + </constructor> + <method name="get_converter" c:identifier="g_converter_input_stream_get_converter" version="2.24"> + <doc xml:space="preserve">Gets the #GConverter that is used by @converter_stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the converter of the converter input stream</doc> + <type name="Converter" c:type="GConverter*"/> + </return-value> + <parameters> + <instance-parameter name="converter_stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GConverterInputStream</doc> + <type name="ConverterInputStream" c:type="GConverterInputStream*"/> + </instance-parameter> + </parameters> + </method> + <property name="converter" writable="1" construct-only="1" transfer-ownership="none"> + <type name="Converter"/> + </property> + <field name="parent_instance"> + <type name="FilterInputStream" c:type="GFilterInputStream"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="ConverterInputStreamPrivate" c:type="GConverterInputStreamPrivate*"/> + </field> + </class> + <record name="ConverterInputStreamClass" c:type="GConverterInputStreamClass" glib:is-gtype-struct-for="ConverterInputStream"> + <field name="parent_class"> + <type name="FilterInputStreamClass" c:type="GFilterInputStreamClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="ConverterInputStreamPrivate" c:type="GConverterInputStreamPrivate" disguised="1"/> + <class name="ConverterOutputStream" c:symbol-prefix="converter_output_stream" c:type="GConverterOutputStream" parent="FilterOutputStream" glib:type-name="GConverterOutputStream" glib:get-type="g_converter_output_stream_get_type" glib:type-struct="ConverterOutputStreamClass"> + <doc xml:space="preserve">Converter output stream implements #GOutputStream and allows +conversion of data of various types during reading. + +As of GLib 2.34, #GConverterOutputStream implements +#GPollableOutputStream.</doc> + <implements name="PollableOutputStream"/> + <constructor name="new" c:identifier="g_converter_output_stream_new"> + <doc xml:space="preserve">Creates a new converter output stream for the @base_stream.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </return-value> + <parameters> + <parameter name="base_stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="converter" transfer-ownership="none"> + <doc xml:space="preserve">a #GConverter</doc> + <type name="Converter" c:type="GConverter*"/> + </parameter> + </parameters> + </constructor> + <method name="get_converter" c:identifier="g_converter_output_stream_get_converter" version="2.24"> + <doc xml:space="preserve">Gets the #GConverter that is used by @converter_stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the converter of the converter output stream</doc> + <type name="Converter" c:type="GConverter*"/> + </return-value> + <parameters> + <instance-parameter name="converter_stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GConverterOutputStream</doc> + <type name="ConverterOutputStream" c:type="GConverterOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <property name="converter" writable="1" construct-only="1" transfer-ownership="none"> + <type name="Converter"/> + </property> + <field name="parent_instance"> + <type name="FilterOutputStream" c:type="GFilterOutputStream"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="ConverterOutputStreamPrivate" c:type="GConverterOutputStreamPrivate*"/> + </field> + </class> + <record name="ConverterOutputStreamClass" c:type="GConverterOutputStreamClass" glib:is-gtype-struct-for="ConverterOutputStream"> + <field name="parent_class"> + <type name="FilterOutputStreamClass" c:type="GFilterOutputStreamClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="ConverterOutputStreamPrivate" c:type="GConverterOutputStreamPrivate" disguised="1"/> + <enumeration name="ConverterResult" version="2.24" glib:type-name="GConverterResult" glib:get-type="g_converter_result_get_type" c:type="GConverterResult"> + <doc xml:space="preserve">Results returned from g_converter_convert().</doc> + <member name="error" value="0" c:identifier="G_CONVERTER_ERROR" glib:nick="error"> + <doc xml:space="preserve">There was an error during conversion.</doc> + </member> + <member name="converted" value="1" c:identifier="G_CONVERTER_CONVERTED" glib:nick="converted"> + <doc xml:space="preserve">Some data was consumed or produced</doc> + </member> + <member name="finished" value="2" c:identifier="G_CONVERTER_FINISHED" glib:nick="finished"> + <doc xml:space="preserve">The conversion is finished</doc> + </member> + <member name="flushed" value="3" c:identifier="G_CONVERTER_FLUSHED" glib:nick="flushed"> + <doc xml:space="preserve">Flushing is finished</doc> + </member> + </enumeration> + <class name="Credentials" c:symbol-prefix="credentials" c:type="GCredentials" version="2.26" parent="GObject.Object" glib:type-name="GCredentials" glib:get-type="g_credentials_get_type" glib:type-struct="CredentialsClass"> + <doc xml:space="preserve">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 Apple operating systems (including iOS, tvOS, and macOS), +the native credential type is a `struct xucred`. +This corresponds to %G_CREDENTIALS_TYPE_APPLE_XUCRED. + +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.</doc> + <constructor name="new" c:identifier="g_credentials_new" version="2.26"> + <doc xml:space="preserve">Creates a new #GCredentials object with credentials matching the +the current process.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GCredentials. Free with g_object_unref().</doc> + <type name="Credentials" c:type="GCredentials*"/> + </return-value> + </constructor> + <method name="get_native" c:identifier="g_credentials_get_native" version="2.26" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The pointer to native credentials or + %NULL if 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.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="credentials" transfer-ownership="none"> + <doc xml:space="preserve">A #GCredentials.</doc> + <type name="Credentials" c:type="GCredentials*"/> + </instance-parameter> + <parameter name="native_type" transfer-ownership="none"> + <doc xml:space="preserve">The type of native credentials to get.</doc> + <type name="CredentialsType" c:type="GCredentialsType"/> + </parameter> + </parameters> + </method> + <method name="get_unix_pid" c:identifier="g_credentials_get_unix_pid" version="2.36" throws="1"> + <doc xml:space="preserve">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 (for example this is the case for +%G_CREDENTIALS_TYPE_APPLE_XUCRED).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The UNIX process ID, or `-1` if @error is set.</doc> + <type name="gint" c:type="pid_t"/> + </return-value> + <parameters> + <instance-parameter name="credentials" transfer-ownership="none"> + <doc xml:space="preserve">A #GCredentials</doc> + <type name="Credentials" c:type="GCredentials*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_unix_user" c:identifier="g_credentials_get_unix_user" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The UNIX user identifier or `-1` if @error is set.</doc> + <type name="guint" c:type="uid_t"/> + </return-value> + <parameters> + <instance-parameter name="credentials" transfer-ownership="none"> + <doc xml:space="preserve">A #GCredentials</doc> + <type name="Credentials" c:type="GCredentials*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_same_user" c:identifier="g_credentials_is_same_user" version="2.26" throws="1"> + <doc xml:space="preserve">Checks if @credentials and @other_credentials is the same user. + +This operation can fail if #GCredentials is not supported on the +the OS.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @credentials and @other_credentials has the same +user, %FALSE otherwise or if @error is set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="credentials" transfer-ownership="none"> + <doc xml:space="preserve">A #GCredentials.</doc> + <type name="Credentials" c:type="GCredentials*"/> + </instance-parameter> + <parameter name="other_credentials" transfer-ownership="none"> + <doc xml:space="preserve">A #GCredentials.</doc> + <type name="Credentials" c:type="GCredentials*"/> + </parameter> + </parameters> + </method> + <method name="set_native" c:identifier="g_credentials_set_native" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="credentials" transfer-ownership="none"> + <doc xml:space="preserve">A #GCredentials.</doc> + <type name="Credentials" c:type="GCredentials*"/> + </instance-parameter> + <parameter name="native_type" transfer-ownership="none"> + <doc xml:space="preserve">The type of native credentials to set.</doc> + <type name="CredentialsType" c:type="GCredentialsType"/> + </parameter> + <parameter name="native" transfer-ownership="none"> + <doc xml:space="preserve">A pointer to native credentials.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="set_unix_user" c:identifier="g_credentials_set_unix_user" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @uid was set, %FALSE if error is set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="credentials" transfer-ownership="none"> + <doc xml:space="preserve">A #GCredentials.</doc> + <type name="Credentials" c:type="GCredentials*"/> + </instance-parameter> + <parameter name="uid" transfer-ownership="none"> + <doc xml:space="preserve">The UNIX user identifier to set.</doc> + <type name="guint" c:type="uid_t"/> + </parameter> + </parameters> + </method> + <method name="to_string" c:identifier="g_credentials_to_string" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A string that should be freed with g_free().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="credentials" transfer-ownership="none"> + <doc xml:space="preserve">A #GCredentials object.</doc> + <type name="Credentials" c:type="GCredentials*"/> + </instance-parameter> + </parameters> + </method> + </class> + <record name="CredentialsClass" c:type="GCredentialsClass" disguised="1" glib:is-gtype-struct-for="Credentials" version="2.26"> + <doc xml:space="preserve">Class structure for #GCredentials.</doc> + </record> + <enumeration name="CredentialsType" version="2.26" glib:type-name="GCredentialsType" glib:get-type="g_credentials_type_get_type" c:type="GCredentialsType"> + <doc xml:space="preserve">Enumeration describing different kinds of native credential types.</doc> + <member name="invalid" value="0" c:identifier="G_CREDENTIALS_TYPE_INVALID" glib:nick="invalid"> + <doc xml:space="preserve">Indicates an invalid native credential type.</doc> + </member> + <member name="linux_ucred" value="1" c:identifier="G_CREDENTIALS_TYPE_LINUX_UCRED" glib:nick="linux-ucred"> + <doc xml:space="preserve">The native credentials type is a `struct ucred`.</doc> + </member> + <member name="freebsd_cmsgcred" value="2" c:identifier="G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED" glib:nick="freebsd-cmsgcred"> + <doc xml:space="preserve">The native credentials type is a `struct cmsgcred`.</doc> + </member> + <member name="openbsd_sockpeercred" value="3" c:identifier="G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED" glib:nick="openbsd-sockpeercred"> + <doc xml:space="preserve">The native credentials type is a `struct sockpeercred`. Added in 2.30.</doc> + </member> + <member name="solaris_ucred" value="4" c:identifier="G_CREDENTIALS_TYPE_SOLARIS_UCRED" glib:nick="solaris-ucred"> + <doc xml:space="preserve">The native credentials type is a `ucred_t`. Added in 2.40.</doc> + </member> + <member name="netbsd_unpcbid" value="5" c:identifier="G_CREDENTIALS_TYPE_NETBSD_UNPCBID" glib:nick="netbsd-unpcbid"> + <doc xml:space="preserve">The native credentials type is a `struct unpcbid`. Added in 2.42.</doc> + </member> + <member name="apple_xucred" value="6" c:identifier="G_CREDENTIALS_TYPE_APPLE_XUCRED" glib:nick="apple-xucred"> + <doc xml:space="preserve">The native credentials type is a `struct xucred`. Added in 2.66.</doc> + </member> + </enumeration> + <function-macro name="DATAGRAM_BASED" c:identifier="G_DATAGRAM_BASED" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DATAGRAM_BASED_GET_IFACE" c:identifier="G_DATAGRAM_BASED_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DATA_INPUT_STREAM" c:identifier="G_DATA_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DATA_INPUT_STREAM_CLASS" c:identifier="G_DATA_INPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DATA_INPUT_STREAM_GET_CLASS" c:identifier="G_DATA_INPUT_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DATA_OUTPUT_STREAM" c:identifier="G_DATA_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DATA_OUTPUT_STREAM_CLASS" c:identifier="G_DATA_OUTPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DATA_OUTPUT_STREAM_GET_CLASS" c:identifier="G_DATA_OUTPUT_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_ACTION_GROUP" c:identifier="G_DBUS_ACTION_GROUP" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_ACTION_GROUP_CLASS" c:identifier="G_DBUS_ACTION_GROUP_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_ACTION_GROUP_GET_CLASS" c:identifier="G_DBUS_ACTION_GROUP_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_AUTH_OBSERVER" c:identifier="G_DBUS_AUTH_OBSERVER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_CONNECTION" c:identifier="G_DBUS_CONNECTION" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_INTERFACE" c:identifier="G_DBUS_INTERFACE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_INTERFACE_GET_IFACE" c:identifier="G_DBUS_INTERFACE_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_INTERFACE_SKELETON" c:identifier="G_DBUS_INTERFACE_SKELETON" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_INTERFACE_SKELETON_CLASS" c:identifier="G_DBUS_INTERFACE_SKELETON_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_INTERFACE_SKELETON_GET_CLASS" c:identifier="G_DBUS_INTERFACE_SKELETON_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_MENU_MODEL" c:identifier="G_DBUS_MENU_MODEL" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_MESSAGE" c:identifier="G_DBUS_MESSAGE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_METHOD_INVOCATION" c:identifier="G_DBUS_METHOD_INVOCATION" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_OBJECT" c:identifier="G_DBUS_OBJECT" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_OBJECT_GET_IFACE" c:identifier="G_DBUS_OBJECT_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_OBJECT_MANAGER" c:identifier="G_DBUS_OBJECT_MANAGER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_OBJECT_MANAGER_CLIENT" c:identifier="G_DBUS_OBJECT_MANAGER_CLIENT" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_OBJECT_MANAGER_CLIENT_CLASS" c:identifier="G_DBUS_OBJECT_MANAGER_CLIENT_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_OBJECT_MANAGER_CLIENT_GET_CLASS" c:identifier="G_DBUS_OBJECT_MANAGER_CLIENT_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_OBJECT_MANAGER_GET_IFACE" c:identifier="G_DBUS_OBJECT_MANAGER_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_OBJECT_MANAGER_SERVER" c:identifier="G_DBUS_OBJECT_MANAGER_SERVER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_OBJECT_MANAGER_SERVER_CLASS" c:identifier="G_DBUS_OBJECT_MANAGER_SERVER_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_OBJECT_MANAGER_SERVER_GET_CLASS" c:identifier="G_DBUS_OBJECT_MANAGER_SERVER_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_OBJECT_PROXY" c:identifier="G_DBUS_OBJECT_PROXY" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_OBJECT_PROXY_CLASS" c:identifier="G_DBUS_OBJECT_PROXY_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_OBJECT_PROXY_GET_CLASS" c:identifier="G_DBUS_OBJECT_PROXY_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_OBJECT_SKELETON" c:identifier="G_DBUS_OBJECT_SKELETON" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_OBJECT_SKELETON_CLASS" c:identifier="G_DBUS_OBJECT_SKELETON_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_OBJECT_SKELETON_GET_CLASS" c:identifier="G_DBUS_OBJECT_SKELETON_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_PROXY" c:identifier="G_DBUS_PROXY" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_PROXY_CLASS" c:identifier="G_DBUS_PROXY_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_PROXY_GET_CLASS" c:identifier="G_DBUS_PROXY_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DBUS_SERVER" c:identifier="G_DBUS_SERVER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <class name="DBusActionGroup" c:symbol-prefix="dbus_action_group" c:type="GDBusActionGroup" parent="GObject.Object" glib:type-name="GDBusActionGroup" glib:get-type="g_dbus_action_group_get_type"> + <doc xml:space="preserve">#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().</doc> + <implements name="ActionGroup"/> + <implements name="RemoteActionGroup"/> + <function name="get" c:identifier="g_dbus_action_group_get" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GDBusActionGroup</doc> + <type name="DBusActionGroup" c:type="GDBusActionGroup*"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="bus_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the bus name which exports the action + group or %NULL if @connection is not a message bus connection</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">the object path at which the action group is exported</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + </class> + <record name="DBusAnnotationInfo" c:type="GDBusAnnotationInfo" version="2.26" glib:type-name="GDBusAnnotationInfo" glib:get-type="g_dbus_annotation_info_get_type" c:symbol-prefix="dbus_annotation_info"> + <doc xml:space="preserve">Information about an annotation.</doc> + <field name="ref_count" writable="1"> + <doc xml:space="preserve">The reference count or -1 if statically allocated.</doc> + <type name="gint" c:type="volatile gint"/> + </field> + <field name="key" writable="1"> + <doc xml:space="preserve">The name of the annotation, e.g. "org.freedesktop.DBus.Deprecated".</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="value" writable="1"> + <doc xml:space="preserve">The value of the annotation.</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="annotations" writable="1"> + <doc xml:space="preserve">A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.</doc> + <array c:type="GDBusAnnotationInfo**"> + <type name="DBusAnnotationInfo" c:type="GDBusAnnotationInfo*"/> + </array> + </field> + <method name="ref" c:identifier="g_dbus_annotation_info_ref" version="2.26"> + <doc xml:space="preserve">If @info is statically allocated does nothing. Otherwise increases +the reference count.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">The same @info.</doc> + <type name="DBusAnnotationInfo" c:type="GDBusAnnotationInfo*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusNodeInfo</doc> + <type name="DBusAnnotationInfo" c:type="GDBusAnnotationInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_dbus_annotation_info_unref" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusAnnotationInfo.</doc> + <type name="DBusAnnotationInfo" c:type="GDBusAnnotationInfo*"/> + </instance-parameter> + </parameters> + </method> + <function name="lookup" c:identifier="g_dbus_annotation_info_lookup" version="2.26"> + <doc xml:space="preserve">Looks up the value of an annotation. + +The cost of this function is O(n) in number of annotations.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The value or %NULL if not found. Do not free, it is owned by @annotations.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="annotations" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A %NULL-terminated array of annotations or %NULL.</doc> + <array c:type="GDBusAnnotationInfo**"> + <type name="DBusAnnotationInfo" c:type="GDBusAnnotationInfo*"/> + </array> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">The name of the annotation to look up.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + </record> + <record name="DBusArgInfo" c:type="GDBusArgInfo" version="2.26" glib:type-name="GDBusArgInfo" glib:get-type="g_dbus_arg_info_get_type" c:symbol-prefix="dbus_arg_info"> + <doc xml:space="preserve">Information about an argument for a method or a signal.</doc> + <field name="ref_count" writable="1"> + <doc xml:space="preserve">The reference count or -1 if statically allocated.</doc> + <type name="gint" c:type="volatile gint"/> + </field> + <field name="name" writable="1"> + <doc xml:space="preserve">Name of the argument, e.g. @unix_user_id.</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="signature" writable="1"> + <doc xml:space="preserve">D-Bus signature of the argument (a single complete type).</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="annotations" writable="1"> + <doc xml:space="preserve">A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.</doc> + <array c:type="GDBusAnnotationInfo**"> + <type name="DBusAnnotationInfo" c:type="GDBusAnnotationInfo*"/> + </array> + </field> + <method name="ref" c:identifier="g_dbus_arg_info_ref" version="2.26"> + <doc xml:space="preserve">If @info is statically allocated does nothing. Otherwise increases +the reference count.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">The same @info.</doc> + <type name="DBusArgInfo" c:type="GDBusArgInfo*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusArgInfo</doc> + <type name="DBusArgInfo" c:type="GDBusArgInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_dbus_arg_info_unref" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusArgInfo.</doc> + <type name="DBusArgInfo" c:type="GDBusArgInfo*"/> + </instance-parameter> + </parameters> + </method> + </record> + <class name="DBusAuthObserver" c:symbol-prefix="dbus_auth_observer" c:type="GDBusAuthObserver" version="2.26" parent="GObject.Object" glib:type-name="GDBusAuthObserver" glib:get-type="g_dbus_auth_observer_get_type"> + <doc xml:space="preserve">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, since GLib 2.68, you should use the +%G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag. It’s equivalent +to the following signal handler: + +|[<!-- 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; +} +]|</doc> + <constructor name="new" c:identifier="g_dbus_auth_observer_new" version="2.26"> + <doc xml:space="preserve">Creates a new #GDBusAuthObserver object.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusAuthObserver. Free with g_object_unref().</doc> + <type name="DBusAuthObserver" c:type="GDBusAuthObserver*"/> + </return-value> + </constructor> + <method name="allow_mechanism" c:identifier="g_dbus_auth_observer_allow_mechanism" version="2.34"> + <doc xml:space="preserve">Emits the #GDBusAuthObserver::allow-mechanism signal on @observer.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="observer" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusAuthObserver.</doc> + <type name="DBusAuthObserver" c:type="GDBusAuthObserver*"/> + </instance-parameter> + <parameter name="mechanism" transfer-ownership="none"> + <doc xml:space="preserve">The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="authorize_authenticated_peer" c:identifier="g_dbus_auth_observer_authorize_authenticated_peer" version="2.26"> + <doc xml:space="preserve">Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the peer is authorized, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="observer" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusAuthObserver.</doc> + <type name="DBusAuthObserver" c:type="GDBusAuthObserver*"/> + </instance-parameter> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GIOStream for the #GDBusConnection.</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="credentials" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Credentials received from the peer or %NULL.</doc> + <type name="Credentials" c:type="GCredentials*"/> + </parameter> + </parameters> + </method> + <glib:signal name="allow-mechanism" when="last" version="2.34"> + <doc xml:space="preserve">Emitted to check if @mechanism is allowed to be used.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="mechanism" transfer-ownership="none"> + <doc xml:space="preserve">The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="authorize-authenticated-peer" when="last" version="2.26"> + <doc xml:space="preserve">Emitted to check if a peer that is successfully authenticated +is authorized.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the peer is authorized, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GIOStream for the #GDBusConnection.</doc> + <type name="IOStream"/> + </parameter> + <parameter name="credentials" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Credentials received from the peer or %NULL.</doc> + <type name="Credentials"/> + </parameter> + </parameters> + </glib:signal> + </class> + <bitfield name="DBusCallFlags" version="2.26" glib:type-name="GDBusCallFlags" glib:get-type="g_dbus_call_flags_get_type" c:type="GDBusCallFlags"> + <doc xml:space="preserve">Flags used in g_dbus_connection_call() and similar APIs.</doc> + <member name="none" value="0" c:identifier="G_DBUS_CALL_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="no_auto_start" value="1" c:identifier="G_DBUS_CALL_FLAGS_NO_AUTO_START" glib:nick="no-auto-start"> + <doc xml:space="preserve">The bus must not launch +an owner for the destination name in response to this method +invocation.</doc> + </member> + <member name="allow_interactive_authorization" value="2" c:identifier="G_DBUS_CALL_FLAGS_ALLOW_INTERACTIVE_AUTHORIZATION" glib:nick="allow-interactive-authorization"> + <doc xml:space="preserve">the caller is prepared to +wait for interactive authorization. Since 2.46.</doc> + </member> + </bitfield> + <bitfield name="DBusCapabilityFlags" version="2.26" glib:type-name="GDBusCapabilityFlags" glib:get-type="g_dbus_capability_flags_get_type" c:type="GDBusCapabilityFlags"> + <doc xml:space="preserve">Capabilities negotiated with the remote peer.</doc> + <member name="none" value="0" c:identifier="G_DBUS_CAPABILITY_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="unix_fd_passing" value="1" c:identifier="G_DBUS_CAPABILITY_FLAGS_UNIX_FD_PASSING" glib:nick="unix-fd-passing"> + <doc xml:space="preserve">The connection +supports exchanging UNIX file descriptors with the remote peer.</doc> + </member> + </bitfield> + <class name="DBusConnection" c:symbol-prefix="dbus_connection" c:type="GDBusConnection" version="2.26" parent="GObject.Object" glib:type-name="GDBusConnection" glib:get-type="g_dbus_connection_get_type"> + <doc xml:space="preserve">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)</doc> + <implements name="AsyncInitable"/> + <implements name="Initable"/> + <constructor name="new_finish" c:identifier="g_dbus_connection_new_finish" version="2.26" throws="1"> + <doc xml:space="preserve">Finishes an operation started with g_dbus_connection_new().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GDBusConnection or %NULL if @error is set. Free + with g_object_unref().</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </return-value> + <parameters> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult obtained from the #GAsyncReadyCallback + passed to g_dbus_connection_new().</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_for_address_finish" c:identifier="g_dbus_connection_new_for_address_finish" version="2.26" throws="1"> + <doc xml:space="preserve">Finishes an operation started with g_dbus_connection_new_for_address().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GDBusConnection or %NULL if @error is set. + Free with g_object_unref().</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </return-value> + <parameters> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult obtained from the #GAsyncReadyCallback passed + to g_dbus_connection_new()</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_for_address_sync" c:identifier="g_dbus_connection_new_for_address_sync" version="2.26" throws="1"> + <doc xml:space="preserve">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, +%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS or +%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER 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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GDBusConnection or %NULL if @error is set. + Free with g_object_unref().</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a D-Bus address</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to make the connection</doc> + <type name="DBusConnectionFlags" c:type="GDBusConnectionFlags"/> + </parameter> + <parameter name="observer" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GDBusAuthObserver or %NULL</doc> + <type name="DBusAuthObserver" c:type="GDBusAuthObserver*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_sync" c:identifier="g_dbus_connection_new_sync" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GDBusConnection or %NULL if @error is set. + Free with g_object_unref().</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="guid" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the GUID to use if authenticating as a server or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to make the connection</doc> + <type name="DBusConnectionFlags" c:type="GDBusConnectionFlags"/> + </parameter> + <parameter name="observer" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GDBusAuthObserver or %NULL</doc> + <type name="DBusAuthObserver" c:type="GDBusAuthObserver*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </constructor> + <function name="new" c:identifier="g_dbus_connection_new" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="guid" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the GUID to use if authenticating as a server or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to make the connection</doc> + <type name="DBusConnectionFlags" c:type="GDBusConnectionFlags"/> + </parameter> + <parameter name="observer" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GDBusAuthObserver or %NULL</doc> + <type name="DBusAuthObserver" c:type="GDBusAuthObserver*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="new_for_address" c:identifier="g_dbus_connection_new_for_address" version="2.26"> + <doc xml:space="preserve">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, +%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS or +%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER 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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a D-Bus address</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags describing how to make the connection</doc> + <type name="DBusConnectionFlags" c:type="GDBusConnectionFlags"/> + </parameter> + <parameter name="observer" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GDBusAuthObserver or %NULL</doc> + <type name="DBusAuthObserver" c:type="GDBusAuthObserver*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <method name="add_filter" c:identifier="g_dbus_connection_add_filter" version="2.26"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a filter identifier that can be used with + g_dbus_connection_remove_filter()</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="filter_function" transfer-ownership="none" scope="notified" closure="1" destroy="2"> + <doc xml:space="preserve">a filter function</doc> + <type name="DBusMessageFilterFunction" c:type="GDBusMessageFilterFunction"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to @filter_function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="user_data_free_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">function to free @user_data with when filter + is removed or %NULL</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="call" c:identifier="g_dbus_connection_call" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="bus_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a unique or well-known bus name or %NULL if + @connection is not a message bus connection</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">path of remote object</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">D-Bus interface to invoke method on</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="method_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the method to invoke</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant tuple with parameters for the method + or %NULL if not passing parameters</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="reply_type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected type of the reply (which will be a + tuple), or %NULL</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags from the #GDBusCallFlags enumeration</doc> + <type name="DBusCallFlags" c:type="GDBusCallFlags"/> + </parameter> + <parameter name="timeout_msec" transfer-ownership="none"> + <doc xml:space="preserve">the timeout in milliseconds, -1 to use the default + timeout or %G_MAXINT for no timeout</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="10"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request + is satisfied or %NULL if you don't care about the result of the + method invocation</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="call_finish" c:identifier="g_dbus_connection_call_finish" version="2.26" throws="1"> + <doc xml:space="preserve">Finishes an operation started with g_dbus_connection_call().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">%NULL if @error is set. Otherwise a non-floating + #GVariant tuple with return values. Free with g_variant_unref().</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call()</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="call_sync" c:identifier="g_dbus_connection_call_sync" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">%NULL if @error is set. Otherwise a non-floating + #GVariant tuple with return values. Free with g_variant_unref().</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="bus_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a unique or well-known bus name or %NULL if + @connection is not a message bus connection</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">path of remote object</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">D-Bus interface to invoke method on</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="method_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the method to invoke</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant tuple with parameters for the method + or %NULL if not passing parameters</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="reply_type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected type of the reply, or %NULL</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags from the #GDBusCallFlags enumeration</doc> + <type name="DBusCallFlags" c:type="GDBusCallFlags"/> + </parameter> + <parameter name="timeout_msec" transfer-ownership="none"> + <doc xml:space="preserve">the timeout in milliseconds, -1 to use the default + timeout or %G_MAXINT for no timeout</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="call_with_unix_fd_list" c:identifier="g_dbus_connection_call_with_unix_fd_list" version="2.30"> + <doc xml:space="preserve">Like g_dbus_connection_call() but also takes a #GUnixFDList object. + +The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE +values in the body of the message. For example, if a message contains +two file descriptors, @fd_list would have length 2, and +`g_variant_new_handle (0)` and `g_variant_new_handle (1)` would appear +somewhere in the body of the message (not necessarily in that order!) +to represent the file descriptors at indexes 0 and 1 respectively. + +When designing D-Bus APIs that are intended to be interoperable, +please note that non-GDBus implementations of D-Bus can usually only +access file descriptors if they are referenced in this way by a +value of type %G_VARIANT_TYPE_HANDLE in the body of the message. + +This method is only available on UNIX.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="bus_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a unique or well-known bus name or %NULL if + @connection is not a message bus connection</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">path of remote object</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">D-Bus interface to invoke method on</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="method_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the method to invoke</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant tuple with parameters for the method + or %NULL if not passing parameters</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="reply_type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected type of the reply, or %NULL</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags from the #GDBusCallFlags enumeration</doc> + <type name="DBusCallFlags" c:type="GDBusCallFlags"/> + </parameter> + <parameter name="timeout_msec" transfer-ownership="none"> + <doc xml:space="preserve">the timeout in milliseconds, -1 to use the default + timeout or %G_MAXINT for no timeout</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="fd_list" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GUnixFDList or %NULL</doc> + <type name="UnixFDList" c:type="GUnixFDList*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="11"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is + satisfied or %NULL if you don't * care about the result of the + method invocation</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The data to pass to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="call_with_unix_fd_list_finish" c:identifier="g_dbus_connection_call_with_unix_fd_list_finish" version="2.30" throws="1"> + <doc xml:space="preserve">Finishes an operation started with g_dbus_connection_call_with_unix_fd_list(). + +The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE +values in the body of the message. For example, +if g_variant_get_handle() returns 5, that is intended to be a reference +to the file descriptor that can be accessed by +`g_unix_fd_list_get (*out_fd_list, 5, ...)`. + +When designing D-Bus APIs that are intended to be interoperable, +please note that non-GDBus implementations of D-Bus can usually only +access file descriptors if they are referenced in this way by a +value of type %G_VARIANT_TYPE_HANDLE in the body of the message.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">%NULL if @error is set. Otherwise a non-floating + #GVariant tuple with return values. Free with g_variant_unref().</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="out_fd_list" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for a #GUnixFDList or %NULL</doc> + <type name="UnixFDList" c:type="GUnixFDList**"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult obtained from the #GAsyncReadyCallback passed to + g_dbus_connection_call_with_unix_fd_list()</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="call_with_unix_fd_list_sync" c:identifier="g_dbus_connection_call_with_unix_fd_list_sync" version="2.30" throws="1"> + <doc xml:space="preserve">Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects. +See g_dbus_connection_call_with_unix_fd_list() and +g_dbus_connection_call_with_unix_fd_list_finish() for more details. + +This method is only available on UNIX.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">%NULL if @error is set. Otherwise a non-floating + #GVariant tuple with return values. Free with g_variant_unref().</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="bus_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a unique or well-known bus name or %NULL + if @connection is not a message bus connection</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">path of remote object</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">D-Bus interface to invoke method on</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="method_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the method to invoke</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant tuple with parameters for + the method or %NULL if not passing parameters</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="reply_type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected type of the reply, or %NULL</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags from the #GDBusCallFlags enumeration</doc> + <type name="DBusCallFlags" c:type="GDBusCallFlags"/> + </parameter> + <parameter name="timeout_msec" transfer-ownership="none"> + <doc xml:space="preserve">the timeout in milliseconds, -1 to use the default + timeout or %G_MAXINT for no timeout</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="fd_list" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GUnixFDList or %NULL</doc> + <type name="UnixFDList" c:type="GUnixFDList*"/> + </parameter> + <parameter name="out_fd_list" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for a #GUnixFDList or %NULL</doc> + <type name="UnixFDList" c:type="GUnixFDList**"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="close" c:identifier="g_dbus_connection_close" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is + satisfied or %NULL if you don't care about the result</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="close_finish" c:identifier="g_dbus_connection_close_finish" version="2.26" throws="1"> + <doc xml:space="preserve">Finishes an operation started with g_dbus_connection_close().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation succeeded, %FALSE if @error is set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult obtained from the #GAsyncReadyCallback passed + to g_dbus_connection_close()</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="close_sync" c:identifier="g_dbus_connection_close_sync" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation succeeded, %FALSE if @error is set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="emit_signal" c:identifier="g_dbus_connection_emit_signal" version="2.26" throws="1"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE unless @error is set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="destination_bus_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the unique bus name for the destination + for the signal or %NULL to emit to all listeners</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">path of remote object</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">D-Bus interface to emit a signal on</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="signal_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the signal to emit</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant tuple with parameters for the signal + or %NULL if not passing parameters</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="export_action_group" c:identifier="g_dbus_connection_export_action_group" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ID of the export (never zero), or 0 in case of failure</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">a D-Bus object path</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="action_group" transfer-ownership="none"> + <doc xml:space="preserve">a #GActionGroup</doc> + <type name="ActionGroup" c:type="GActionGroup*"/> + </parameter> + </parameters> + </method> + <method name="export_menu_model" c:identifier="g_dbus_connection_export_menu_model" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ID of the export (never zero), or 0 in case of failure</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">a D-Bus object path</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="menu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + </parameters> + </method> + <method name="flush" c:identifier="g_dbus_connection_flush" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the + request is satisfied or %NULL if you don't care about the result</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="flush_finish" c:identifier="g_dbus_connection_flush_finish" version="2.26" throws="1"> + <doc xml:space="preserve">Finishes an operation started with g_dbus_connection_flush().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation succeeded, %FALSE if @error is set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult obtained from the #GAsyncReadyCallback passed + to g_dbus_connection_flush()</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="flush_sync" c:identifier="g_dbus_connection_flush_sync" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation succeeded, %FALSE if @error is set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="get_capabilities" c:identifier="g_dbus_connection_get_capabilities" version="2.26"> + <doc xml:space="preserve">Gets the capabilities negotiated with the remote peer</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">zero or more flags from the #GDBusCapabilityFlags enumeration</doc> + <type name="DBusCapabilityFlags" c:type="GDBusCapabilityFlags"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_exit_on_close" c:identifier="g_dbus_connection_get_exit_on_close" version="2.26"> + <doc xml:space="preserve">Gets whether the process is terminated when @connection is +closed by the remote peer. See +#GDBusConnection:exit-on-close for more details.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether the process is terminated when @connection is + closed by the remote peer</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_flags" c:identifier="g_dbus_connection_get_flags" version="2.60"> + <doc xml:space="preserve">Gets the flags used to construct this connection</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">zero or more flags from the #GDBusConnectionFlags enumeration</doc> + <type name="DBusConnectionFlags" c:type="GDBusConnectionFlags"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_guid" c:identifier="g_dbus_connection_get_guid" version="2.26"> + <doc xml:space="preserve">The GUID of the peer performing the role of server when +authenticating. See #GDBusConnection:guid for more details.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The GUID. Do not free this string, it is owned by + @connection.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_last_serial" c:identifier="g_dbus_connection_get_last_serial" version="2.34"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the last used serial or zero when no message has been sent + within the current thread</doc> + <type name="guint32" c:type="guint32"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_peer_credentials" c:identifier="g_dbus_connection_get_peer_credentials" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a #GCredentials or %NULL if not + available. Do not free this object, it is owned by @connection.</doc> + <type name="Credentials" c:type="GCredentials*"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_stream" c:identifier="g_dbus_connection_get_stream" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the stream used for IO</doc> + <type name="IOStream" c:type="GIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_unique_name" c:identifier="g_dbus_connection_get_unique_name" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the unique name or %NULL if @connection is not a message + bus connection. Do not free this string, it is owned by + @connection.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_closed" c:identifier="g_dbus_connection_is_closed" version="2.26"> + <doc xml:space="preserve">Gets whether @connection is closed.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the connection is closed, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="register_object" c:identifier="g_dbus_connection_register_object" shadowed-by="register_object_with_closures" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">0 if @error is set, otherwise a registration id (never 0) + that can be used with g_dbus_connection_unregister_object()</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">the object path to register at</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_info" transfer-ownership="none"> + <doc xml:space="preserve">introspection data for the interface</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </parameter> + <parameter name="vtable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GDBusInterfaceVTable to call into or %NULL</doc> + <type name="DBusInterfaceVTable" c:type="const GDBusInterfaceVTable*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to functions in @vtable</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="user_data_free_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">function to call when the object path is unregistered</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="register_object_with_closures" c:identifier="g_dbus_connection_register_object_with_closures" shadows="register_object" version="2.46" throws="1"> + <doc xml:space="preserve">Version of g_dbus_connection_register_object() using closures instead of a +#GDBusInterfaceVTable for easier binding in other languages.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">0 if @error is set, otherwise a registration ID (never 0) +that can be used with g_dbus_connection_unregister_object() .</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">The object path to register at.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_info" transfer-ownership="none"> + <doc xml:space="preserve">Introspection data for the interface.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </parameter> + <parameter name="method_call_closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">#GClosure for handling incoming method calls.</doc> + <type name="GObject.Closure" c:type="GClosure*"/> + </parameter> + <parameter name="get_property_closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">#GClosure for getting a property.</doc> + <type name="GObject.Closure" c:type="GClosure*"/> + </parameter> + <parameter name="set_property_closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">#GClosure for setting a property.</doc> + <type name="GObject.Closure" c:type="GClosure*"/> + </parameter> + </parameters> + </method> + <method name="register_subtree" c:identifier="g_dbus_connection_register_subtree" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">0 if @error is set, otherwise a subtree registration ID (never 0) +that can be used with g_dbus_connection_unregister_subtree()</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">the object path to register the subtree at</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="vtable" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusSubtreeVTable to enumerate, introspect and + dispatch nodes in the subtree</doc> + <type name="DBusSubtreeVTable" c:type="const GDBusSubtreeVTable*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags used to fine tune the behavior of the subtree</doc> + <type name="DBusSubtreeFlags" c:type="GDBusSubtreeFlags"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to functions in @vtable</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="user_data_free_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">function to call when the subtree is unregistered</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="remove_filter" c:identifier="g_dbus_connection_remove_filter" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="filter_id" transfer-ownership="none"> + <doc xml:space="preserve">an identifier obtained from g_dbus_connection_add_filter()</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="send_message" c:identifier="g_dbus_connection_send_message" version="2.26" throws="1"> + <doc xml:space="preserve">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. While it has a `volatile` +qualifier, this is a historical artifact and the argument passed to it should +not be `volatile`. + +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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the message was well-formed and queued for + transmission, %FALSE if @error is set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusMessage</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting how the message is sent</doc> + <type name="DBusSendMessageFlags" c:type="GDBusSendMessageFlags"/> + </parameter> + <parameter name="out_serial" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for serial number assigned + to @message when sending it or %NULL</doc> + <type name="guint32" c:type="volatile guint32*"/> + </parameter> + </parameters> + </method> + <method name="send_message_with_reply" c:identifier="g_dbus_connection_send_message_with_reply" version="2.26"> + <doc xml:space="preserve">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. While it has a `volatile` +qualifier, this is a historical artifact and the argument passed to it should +not be `volatile`. + +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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusMessage</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting how the message is sent</doc> + <type name="DBusSendMessageFlags" c:type="GDBusSendMessageFlags"/> + </parameter> + <parameter name="timeout_msec" transfer-ownership="none"> + <doc xml:space="preserve">the timeout in milliseconds, -1 to use the default + timeout or %G_MAXINT for no timeout</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="out_serial" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for serial number assigned + to @message when sending it or %NULL</doc> + <type name="guint32" c:type="volatile guint32*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request + is satisfied or %NULL if you don't care about the result</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="send_message_with_reply_finish" c:identifier="g_dbus_connection_send_message_with_reply_finish" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a locked #GDBusMessage or %NULL if @error is set</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult obtained from the #GAsyncReadyCallback passed to + g_dbus_connection_send_message_with_reply()</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="send_message_with_reply_sync" c:identifier="g_dbus_connection_send_message_with_reply_sync" version="2.26" throws="1"> + <doc xml:space="preserve">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. While it has a `volatile` +qualifier, this is a historical artifact and the argument passed to it should +not be `volatile`. + +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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a locked #GDBusMessage that is the reply + to @message or %NULL if @error is set</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusMessage</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting how the message is sent.</doc> + <type name="DBusSendMessageFlags" c:type="GDBusSendMessageFlags"/> + </parameter> + <parameter name="timeout_msec" transfer-ownership="none"> + <doc xml:space="preserve">the timeout in milliseconds, -1 to use the default + timeout or %G_MAXINT for no timeout</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="out_serial" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for serial number + assigned to @message when sending it or %NULL</doc> + <type name="guint32" c:type="volatile guint32*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_exit_on_close" c:identifier="g_dbus_connection_set_exit_on_close" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="exit_on_close" transfer-ownership="none"> + <doc xml:space="preserve">whether the process should be terminated + when @connection is closed by the remote peer</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="signal_subscribe" c:identifier="g_dbus_connection_signal_subscribe" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe()</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="sender" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">sender name to match on (unique or well-known name) + or %NULL to listen from all senders</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">D-Bus interface name to match on or %NULL to + match on all interfaces</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="member" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">D-Bus signal name to match on or %NULL to match on + all signals</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">object path to match on or %NULL to match on + all object paths</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="arg0" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">contents of first string argument to match on or %NULL + to match on all kinds of arguments</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">#GDBusSignalFlags describing how arg0 is used in subscribing to the + signal</doc> + <type name="DBusSignalFlags" c:type="GDBusSignalFlags"/> + </parameter> + <parameter name="callback" transfer-ownership="none" scope="notified" closure="7" destroy="8"> + <doc xml:space="preserve">callback to invoke when there is a signal matching the requested data</doc> + <type name="DBusSignalCallback" c:type="GDBusSignalCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="user_data_free_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">function to free @user_data with when + subscription is removed or %NULL</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="signal_unsubscribe" c:identifier="g_dbus_connection_signal_unsubscribe" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="subscription_id" transfer-ownership="none"> + <doc xml:space="preserve">a subscription id obtained from + g_dbus_connection_signal_subscribe()</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="start_message_processing" c:identifier="g_dbus_connection_start_message_processing" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="unexport_action_group" c:identifier="g_dbus_connection_unexport_action_group" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="export_id" transfer-ownership="none"> + <doc xml:space="preserve">the ID from g_dbus_connection_export_action_group()</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="unexport_menu_model" c:identifier="g_dbus_connection_unexport_menu_model" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="export_id" transfer-ownership="none"> + <doc xml:space="preserve">the ID from g_dbus_connection_export_menu_model()</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="unregister_object" c:identifier="g_dbus_connection_unregister_object" version="2.26"> + <doc xml:space="preserve">Unregisters an object.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the object was unregistered, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="registration_id" transfer-ownership="none"> + <doc xml:space="preserve">a registration id obtained from + g_dbus_connection_register_object()</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="unregister_subtree" c:identifier="g_dbus_connection_unregister_subtree" version="2.26"> + <doc xml:space="preserve">Unregisters a subtree.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the subtree was unregistered, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </instance-parameter> + <parameter name="registration_id" transfer-ownership="none"> + <doc xml:space="preserve">a subtree registration id obtained from + g_dbus_connection_register_subtree()</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <property name="address" version="2.26" readable="0" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus address specifying potential endpoints that can be used +when establishing the connection.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="authentication-observer" version="2.26" readable="0" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusAuthObserver object to assist in the authentication process or %NULL.</doc> + <type name="DBusAuthObserver"/> + </property> + <property name="capabilities" version="2.26" transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GDBusCapabilityFlags enumeration +representing connection features negotiated with the other peer.</doc> + <type name="DBusCapabilityFlags"/> + </property> + <property name="closed" version="2.26" transfer-ownership="none"> + <doc xml:space="preserve">A boolean specifying whether the connection has been closed.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="exit-on-close" version="2.26" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="flags" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GDBusConnectionFlags enumeration.</doc> + <type name="DBusConnectionFlags"/> + </property> + <property name="guid" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="stream" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="IOStream"/> + </property> + <property name="unique-name" version="2.26" transfer-ownership="none"> + <doc xml:space="preserve">The unique name as assigned by the message bus or %NULL if the +connection is not open or not a message bus connection.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <glib:signal name="closed" when="last" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="remote_peer_vanished" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @connection is closed because the + remote peer closed its end of the connection</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="error" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GError with more details about the event or %NULL</doc> + <type name="GLib.Error"/> + </parameter> + </parameters> + </glib:signal> + </class> + <bitfield name="DBusConnectionFlags" version="2.26" glib:type-name="GDBusConnectionFlags" glib:get-type="g_dbus_connection_flags_get_type" c:type="GDBusConnectionFlags"> + <doc xml:space="preserve">Flags used when creating a new #GDBusConnection.</doc> + <member name="none" value="0" c:identifier="G_DBUS_CONNECTION_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="authentication_client" value="1" c:identifier="G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT" glib:nick="authentication-client"> + <doc xml:space="preserve">Perform authentication against server.</doc> + </member> + <member name="authentication_server" value="2" c:identifier="G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER" glib:nick="authentication-server"> + <doc xml:space="preserve">Perform authentication against client.</doc> + </member> + <member name="authentication_allow_anonymous" value="4" c:identifier="G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS" glib:nick="authentication-allow-anonymous"> + <doc xml:space="preserve">When +authenticating as a server, allow the anonymous authentication +method.</doc> + </member> + <member name="message_bus_connection" value="8" c:identifier="G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION" glib:nick="message-bus-connection"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="delay_message_processing" value="16" c:identifier="G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING" glib:nick="delay-message-processing"> + <doc xml:space="preserve">If set, processing of D-Bus messages is +delayed until g_dbus_connection_start_message_processing() is called.</doc> + </member> + </bitfield> + <enumeration name="DBusError" version="2.26" glib:type-name="GDBusError" glib:get-type="g_dbus_error_get_type" c:type="GDBusError" glib:error-domain="g-dbus-error-quark"> + <doc xml:space="preserve">Error codes for the %G_DBUS_ERROR error domain.</doc> + <member name="failed" value="0" c:identifier="G_DBUS_ERROR_FAILED" glib:nick="failed"> + <doc xml:space="preserve">A generic error; "something went wrong" - see the error message for +more.</doc> + </member> + <member name="no_memory" value="1" c:identifier="G_DBUS_ERROR_NO_MEMORY" glib:nick="no-memory"> + <doc xml:space="preserve">There was not enough memory to complete an operation.</doc> + </member> + <member name="service_unknown" value="2" c:identifier="G_DBUS_ERROR_SERVICE_UNKNOWN" glib:nick="service-unknown"> + <doc xml:space="preserve">The bus doesn't know how to launch a service to supply the bus name +you wanted.</doc> + </member> + <member name="name_has_no_owner" value="3" c:identifier="G_DBUS_ERROR_NAME_HAS_NO_OWNER" glib:nick="name-has-no-owner"> + <doc xml:space="preserve">The bus name you referenced doesn't exist (i.e. no application owns +it).</doc> + </member> + <member name="no_reply" value="4" c:identifier="G_DBUS_ERROR_NO_REPLY" glib:nick="no-reply"> + <doc xml:space="preserve">No reply to a message expecting one, usually means a timeout occurred.</doc> + </member> + <member name="io_error" value="5" c:identifier="G_DBUS_ERROR_IO_ERROR" glib:nick="io-error"> + <doc xml:space="preserve">Something went wrong reading or writing to a socket, for example.</doc> + </member> + <member name="bad_address" value="6" c:identifier="G_DBUS_ERROR_BAD_ADDRESS" glib:nick="bad-address"> + <doc xml:space="preserve">A D-Bus bus address was malformed.</doc> + </member> + <member name="not_supported" value="7" c:identifier="G_DBUS_ERROR_NOT_SUPPORTED" glib:nick="not-supported"> + <doc xml:space="preserve">Requested operation isn't supported (like ENOSYS on UNIX).</doc> + </member> + <member name="limits_exceeded" value="8" c:identifier="G_DBUS_ERROR_LIMITS_EXCEEDED" glib:nick="limits-exceeded"> + <doc xml:space="preserve">Some limited resource is exhausted.</doc> + </member> + <member name="access_denied" value="9" c:identifier="G_DBUS_ERROR_ACCESS_DENIED" glib:nick="access-denied"> + <doc xml:space="preserve">Security restrictions don't allow doing what you're trying to do.</doc> + </member> + <member name="auth_failed" value="10" c:identifier="G_DBUS_ERROR_AUTH_FAILED" glib:nick="auth-failed"> + <doc xml:space="preserve">Authentication didn't work.</doc> + </member> + <member name="no_server" value="11" c:identifier="G_DBUS_ERROR_NO_SERVER" glib:nick="no-server"> + <doc xml:space="preserve">Unable to connect to server (probably caused by ECONNREFUSED on a +socket).</doc> + </member> + <member name="timeout" value="12" c:identifier="G_DBUS_ERROR_TIMEOUT" glib:nick="timeout"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="no_network" value="13" c:identifier="G_DBUS_ERROR_NO_NETWORK" glib:nick="no-network"> + <doc xml:space="preserve">No network access (probably ENETUNREACH on a socket).</doc> + </member> + <member name="address_in_use" value="14" c:identifier="G_DBUS_ERROR_ADDRESS_IN_USE" glib:nick="address-in-use"> + <doc xml:space="preserve">Can't bind a socket since its address is in use (i.e. EADDRINUSE).</doc> + </member> + <member name="disconnected" value="15" c:identifier="G_DBUS_ERROR_DISCONNECTED" glib:nick="disconnected"> + <doc xml:space="preserve">The connection is disconnected and you're trying to use it.</doc> + </member> + <member name="invalid_args" value="16" c:identifier="G_DBUS_ERROR_INVALID_ARGS" glib:nick="invalid-args"> + <doc xml:space="preserve">Invalid arguments passed to a method call.</doc> + </member> + <member name="file_not_found" value="17" c:identifier="G_DBUS_ERROR_FILE_NOT_FOUND" glib:nick="file-not-found"> + <doc xml:space="preserve">Missing file.</doc> + </member> + <member name="file_exists" value="18" c:identifier="G_DBUS_ERROR_FILE_EXISTS" glib:nick="file-exists"> + <doc xml:space="preserve">Existing file and the operation you're using does not silently overwrite.</doc> + </member> + <member name="unknown_method" value="19" c:identifier="G_DBUS_ERROR_UNKNOWN_METHOD" glib:nick="unknown-method"> + <doc xml:space="preserve">Method name you invoked isn't known by the object you invoked it on.</doc> + </member> + <member name="timed_out" value="20" c:identifier="G_DBUS_ERROR_TIMED_OUT" glib:nick="timed-out"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="match_rule_not_found" value="21" c:identifier="G_DBUS_ERROR_MATCH_RULE_NOT_FOUND" glib:nick="match-rule-not-found"> + <doc xml:space="preserve">Tried to remove or modify a match rule that didn't exist.</doc> + </member> + <member name="match_rule_invalid" value="22" c:identifier="G_DBUS_ERROR_MATCH_RULE_INVALID" glib:nick="match-rule-invalid"> + <doc xml:space="preserve">The match rule isn't syntactically valid.</doc> + </member> + <member name="spawn_exec_failed" value="23" c:identifier="G_DBUS_ERROR_SPAWN_EXEC_FAILED" glib:nick="spawn-exec-failed"> + <doc xml:space="preserve">While starting a new process, the exec() call failed.</doc> + </member> + <member name="spawn_fork_failed" value="24" c:identifier="G_DBUS_ERROR_SPAWN_FORK_FAILED" glib:nick="spawn-fork-failed"> + <doc xml:space="preserve">While starting a new process, the fork() call failed.</doc> + </member> + <member name="spawn_child_exited" value="25" c:identifier="G_DBUS_ERROR_SPAWN_CHILD_EXITED" glib:nick="spawn-child-exited"> + <doc xml:space="preserve">While starting a new process, the child exited with a status code.</doc> + </member> + <member name="spawn_child_signaled" value="26" c:identifier="G_DBUS_ERROR_SPAWN_CHILD_SIGNALED" glib:nick="spawn-child-signaled"> + <doc xml:space="preserve">While starting a new process, the child exited on a signal.</doc> + </member> + <member name="spawn_failed" value="27" c:identifier="G_DBUS_ERROR_SPAWN_FAILED" glib:nick="spawn-failed"> + <doc xml:space="preserve">While starting a new process, something went wrong.</doc> + </member> + <member name="spawn_setup_failed" value="28" c:identifier="G_DBUS_ERROR_SPAWN_SETUP_FAILED" glib:nick="spawn-setup-failed"> + <doc xml:space="preserve">We failed to setup the environment correctly.</doc> + </member> + <member name="spawn_config_invalid" value="29" c:identifier="G_DBUS_ERROR_SPAWN_CONFIG_INVALID" glib:nick="spawn-config-invalid"> + <doc xml:space="preserve">We failed to setup the config parser correctly.</doc> + </member> + <member name="spawn_service_invalid" value="30" c:identifier="G_DBUS_ERROR_SPAWN_SERVICE_INVALID" glib:nick="spawn-service-invalid"> + <doc xml:space="preserve">Bus name was not valid.</doc> + </member> + <member name="spawn_service_not_found" value="31" c:identifier="G_DBUS_ERROR_SPAWN_SERVICE_NOT_FOUND" glib:nick="spawn-service-not-found"> + <doc xml:space="preserve">Service file not found in system-services directory.</doc> + </member> + <member name="spawn_permissions_invalid" value="32" c:identifier="G_DBUS_ERROR_SPAWN_PERMISSIONS_INVALID" glib:nick="spawn-permissions-invalid"> + <doc xml:space="preserve">Permissions are incorrect on the setuid helper.</doc> + </member> + <member name="spawn_file_invalid" value="33" c:identifier="G_DBUS_ERROR_SPAWN_FILE_INVALID" glib:nick="spawn-file-invalid"> + <doc xml:space="preserve">Service file invalid (Name, User or Exec missing).</doc> + </member> + <member name="spawn_no_memory" value="34" c:identifier="G_DBUS_ERROR_SPAWN_NO_MEMORY" glib:nick="spawn-no-memory"> + <doc xml:space="preserve">Tried to get a UNIX process ID and it wasn't available.</doc> + </member> + <member name="unix_process_id_unknown" value="35" c:identifier="G_DBUS_ERROR_UNIX_PROCESS_ID_UNKNOWN" glib:nick="unix-process-id-unknown"> + <doc xml:space="preserve">Tried to get a UNIX process ID and it wasn't available.</doc> + </member> + <member name="invalid_signature" value="36" c:identifier="G_DBUS_ERROR_INVALID_SIGNATURE" glib:nick="invalid-signature"> + <doc xml:space="preserve">A type signature is not valid.</doc> + </member> + <member name="invalid_file_content" value="37" c:identifier="G_DBUS_ERROR_INVALID_FILE_CONTENT" glib:nick="invalid-file-content"> + <doc xml:space="preserve">A file contains invalid syntax or is otherwise broken.</doc> + </member> + <member name="selinux_security_context_unknown" value="38" c:identifier="G_DBUS_ERROR_SELINUX_SECURITY_CONTEXT_UNKNOWN" glib:nick="selinux-security-context-unknown"> + <doc xml:space="preserve">Asked for SELinux security context and it wasn't available.</doc> + </member> + <member name="adt_audit_data_unknown" value="39" c:identifier="G_DBUS_ERROR_ADT_AUDIT_DATA_UNKNOWN" glib:nick="adt-audit-data-unknown"> + <doc xml:space="preserve">Asked for ADT audit data and it wasn't available.</doc> + </member> + <member name="object_path_in_use" value="40" c:identifier="G_DBUS_ERROR_OBJECT_PATH_IN_USE" glib:nick="object-path-in-use"> + <doc xml:space="preserve">There's already an object with the requested object path.</doc> + </member> + <member name="unknown_object" value="41" c:identifier="G_DBUS_ERROR_UNKNOWN_OBJECT" glib:nick="unknown-object"> + <doc xml:space="preserve">Object you invoked a method on isn't known. Since 2.42</doc> + </member> + <member name="unknown_interface" value="42" c:identifier="G_DBUS_ERROR_UNKNOWN_INTERFACE" glib:nick="unknown-interface"> + <doc xml:space="preserve">Interface you invoked a method on isn't known by the object. Since 2.42</doc> + </member> + <member name="unknown_property" value="43" c:identifier="G_DBUS_ERROR_UNKNOWN_PROPERTY" glib:nick="unknown-property"> + <doc xml:space="preserve">Property you tried to access isn't known by the object. Since 2.42</doc> + </member> + <member name="property_read_only" value="44" c:identifier="G_DBUS_ERROR_PROPERTY_READ_ONLY" glib:nick="property-read-only"> + <doc xml:space="preserve">Property you tried to set is read-only. Since 2.42</doc> + </member> + <function name="encode_gerror" c:identifier="g_dbus_error_encode_gerror" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A D-Bus error name (never %NULL). + Free with g_free().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">A #GError.</doc> + <type name="GLib.Error" c:type="const GError*"/> + </parameter> + </parameters> + </function> + <function name="get_remote_error" c:identifier="g_dbus_error_get_remote_error" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">an allocated string or %NULL if the + D-Bus error name could not be found. Free with g_free().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">a #GError</doc> + <type name="GLib.Error" c:type="const GError*"/> + </parameter> + </parameters> + </function> + <function name="is_remote_error" c:identifier="g_dbus_error_is_remote_error" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @error represents an error from a remote peer, +%FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">A #GError.</doc> + <type name="GLib.Error" c:type="const GError*"/> + </parameter> + </parameters> + </function> + <function name="new_for_dbus_error" c:identifier="g_dbus_error_new_for_dbus_error" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">An allocated #GError. Free with g_error_free().</doc> + <type name="GLib.Error" c:type="GError*"/> + </return-value> + <parameters> + <parameter name="dbus_error_name" transfer-ownership="none"> + <doc xml:space="preserve">D-Bus error name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="dbus_error_message" transfer-ownership="none"> + <doc xml:space="preserve">D-Bus error message.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="quark" c:identifier="g_dbus_error_quark"> + <return-value transfer-ownership="none"> + <type name="GLib.Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="register_error" c:identifier="g_dbus_error_register_error" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the association was created, %FALSE if it already +exists.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="error_domain" transfer-ownership="none"> + <doc xml:space="preserve">A #GQuark for an error domain.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="error_code" transfer-ownership="none"> + <doc xml:space="preserve">An error code.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="dbus_error_name" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus error name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="register_error_domain" c:identifier="g_dbus_error_register_error_domain" version="2.26"> + <doc xml:space="preserve">Helper function for associating a #GError error domain with D-Bus error names. + +While @quark_volatile has a `volatile` qualifier, this is a historical +artifact and the argument passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="error_domain_quark_name" transfer-ownership="none"> + <doc xml:space="preserve">The error domain name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="quark_volatile" transfer-ownership="none"> + <doc xml:space="preserve">A pointer where to store the #GQuark.</doc> + <type name="gsize" c:type="volatile gsize*"/> + </parameter> + <parameter name="entries" transfer-ownership="none"> + <doc xml:space="preserve">A pointer to @num_entries #GDBusErrorEntry struct items.</doc> + <array length="3" zero-terminated="0" c:type="const GDBusErrorEntry*"> + <type name="DBusErrorEntry" c:type="GDBusErrorEntry"/> + </array> + </parameter> + <parameter name="num_entries" transfer-ownership="none"> + <doc xml:space="preserve">Number of items to register.</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="set_dbus_error" c:identifier="g_dbus_error_set_dbus_error" version="2.26" introspectable="0"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">A pointer to a #GError or %NULL.</doc> + <type name="GLib.Error" c:type="GError**"/> + </parameter> + <parameter name="dbus_error_name" transfer-ownership="none"> + <doc xml:space="preserve">D-Bus error name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="dbus_error_message" transfer-ownership="none"> + <doc xml:space="preserve">D-Bus error message.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="format" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">printf()-style format to prepend to @dbus_error_message or %NULL.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">Arguments for @format.</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="set_dbus_error_valist" c:identifier="g_dbus_error_set_dbus_error_valist" version="2.26" introspectable="0"> + <doc xml:space="preserve">Like g_dbus_error_set_dbus_error() but intended for language bindings.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">A pointer to a #GError or %NULL.</doc> + <type name="GLib.Error" c:type="GError**"/> + </parameter> + <parameter name="dbus_error_name" transfer-ownership="none"> + <doc xml:space="preserve">D-Bus error name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="dbus_error_message" transfer-ownership="none"> + <doc xml:space="preserve">D-Bus error message.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="format" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">printf()-style format to prepend to @dbus_error_message or %NULL.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="var_args" transfer-ownership="none"> + <doc xml:space="preserve">Arguments for @format.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </function> + <function name="strip_remote_error" c:identifier="g_dbus_error_strip_remote_error" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if information was stripped, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">A #GError.</doc> + <type name="GLib.Error" c:type="GError*"/> + </parameter> + </parameters> + </function> + <function name="unregister_error" c:identifier="g_dbus_error_unregister_error" version="2.26"> + <doc xml:space="preserve">Destroys an association previously set up with g_dbus_error_register_error().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the association was destroyed, %FALSE if it wasn't found.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="error_domain" transfer-ownership="none"> + <doc xml:space="preserve">A #GQuark for an error domain.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="error_code" transfer-ownership="none"> + <doc xml:space="preserve">An error code.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="dbus_error_name" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus error name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + </enumeration> + <record name="DBusErrorEntry" c:type="GDBusErrorEntry" version="2.26"> + <doc xml:space="preserve">Struct used in g_dbus_error_register_error_domain().</doc> + <field name="error_code" writable="1"> + <doc xml:space="preserve">An error code.</doc> + <type name="gint" c:type="gint"/> + </field> + <field name="dbus_error_name" writable="1"> + <doc xml:space="preserve">The D-Bus error name to associate with @error_code.</doc> + <type name="utf8" c:type="const gchar*"/> + </field> + </record> + <interface name="DBusInterface" c:symbol-prefix="dbus_interface" c:type="GDBusInterface" version="2.30" glib:type-name="GDBusInterface" glib:get-type="g_dbus_interface_get_type" glib:type-struct="DBusInterfaceIface"> + <doc xml:space="preserve">The #GDBusInterface type is the base type for D-Bus interfaces both +on the service side (see #GDBusInterfaceSkeleton) and client side +(see #GDBusProxy).</doc> + <virtual-method name="dup_object" invoker="dup_object" version="2.32"> + <doc xml:space="preserve">Gets the #GDBusObject that @interface_ belongs to, if any.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">A #GDBusObject or %NULL. The returned +reference should be freed with g_object_unref().</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">An exported D-Bus interface.</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_info" invoker="get_info" version="2.30"> + <doc xml:space="preserve">Gets D-Bus introspection information for the D-Bus interface +implemented by @interface_.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceInfo. Do not free.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">An exported D-Bus interface.</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_object" invoker="get_object" version="2.30" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">A #GDBusObject or %NULL. The returned + reference belongs to @interface_ and should not be freed.</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">An exported D-Bus interface</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="set_object" invoker="set_object" version="2.30"> + <doc xml:space="preserve">Sets the #GDBusObject for @interface_ to @object. + +Note that @interface_ will hold a weak reference to @object.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">An exported D-Bus interface.</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </instance-parameter> + <parameter name="object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GDBusObject or %NULL.</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </parameter> + </parameters> + </virtual-method> + <method name="dup_object" c:identifier="g_dbus_interface_dup_object" shadows="get_object" version="2.32"> + <doc xml:space="preserve">Gets the #GDBusObject that @interface_ belongs to, if any.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">A #GDBusObject or %NULL. The returned +reference should be freed with g_object_unref().</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">An exported D-Bus interface.</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_info" c:identifier="g_dbus_interface_get_info" version="2.30"> + <doc xml:space="preserve">Gets D-Bus introspection information for the D-Bus interface +implemented by @interface_.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceInfo. Do not free.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">An exported D-Bus interface.</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_object" c:identifier="g_dbus_interface_get_object" shadowed-by="dup_object" version="2.30" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">A #GDBusObject or %NULL. The returned + reference belongs to @interface_ and should not be freed.</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">An exported D-Bus interface</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_object" c:identifier="g_dbus_interface_set_object" version="2.30"> + <doc xml:space="preserve">Sets the #GDBusObject for @interface_ to @object. + +Note that @interface_ will hold a weak reference to @object.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">An exported D-Bus interface.</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </instance-parameter> + <parameter name="object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GDBusObject or %NULL.</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </parameter> + </parameters> + </method> + </interface> + <callback name="DBusInterfaceGetPropertyFunc" c:type="GDBusInterfaceGetPropertyFunc" version="2.26"> + <doc xml:space="preserve">The type of the @get_property function in #GDBusInterfaceVTable.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="sender" transfer-ownership="none"> + <doc xml:space="preserve">The unique bus name of the remote caller.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">The object path that the method was invoked on.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">The D-Bus interface name for the property.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="property_name" transfer-ownership="none"> + <doc xml:space="preserve">The name of the property to get the value of.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">Return location for error.</doc> + <type name="GLib.Error" c:type="GError**"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">The @user_data #gpointer passed to g_dbus_connection_register_object().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="DBusInterfaceIface" c:type="GDBusInterfaceIface" glib:is-gtype-struct-for="DBusInterface" version="2.30"> + <doc xml:space="preserve">Base type for D-Bus interfaces.</doc> + <field name="parent_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="get_info"> + <callback name="get_info"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceInfo. Do not free.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </return-value> + <parameters> + <parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">An exported D-Bus interface.</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_object"> + <callback name="get_object"> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">A #GDBusObject or %NULL. The returned + reference belongs to @interface_ and should not be freed.</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </return-value> + <parameters> + <parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">An exported D-Bus interface</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="set_object"> + <callback name="set_object"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">An exported D-Bus interface.</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </parameter> + <parameter name="object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GDBusObject or %NULL.</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="dup_object"> + <callback name="dup_object"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">A #GDBusObject or %NULL. The returned +reference should be freed with g_object_unref().</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </return-value> + <parameters> + <parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">An exported D-Bus interface.</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <record name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo" version="2.26" glib:type-name="GDBusInterfaceInfo" glib:get-type="g_dbus_interface_info_get_type" c:symbol-prefix="dbus_interface_info"> + <doc xml:space="preserve">Information about a D-Bus interface.</doc> + <field name="ref_count" writable="1"> + <doc xml:space="preserve">The reference count or -1 if statically allocated.</doc> + <type name="gint" c:type="volatile gint"/> + </field> + <field name="name" writable="1"> + <doc xml:space="preserve">The name of the D-Bus interface, e.g. "org.freedesktop.DBus.Properties".</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="methods" writable="1"> + <doc xml:space="preserve">A pointer to a %NULL-terminated array of pointers to #GDBusMethodInfo structures or %NULL if there are no methods.</doc> + <array c:type="GDBusMethodInfo**"> + <type name="DBusMethodInfo" c:type="GDBusMethodInfo*"/> + </array> + </field> + <field name="signals" writable="1"> + <doc xml:space="preserve">A pointer to a %NULL-terminated array of pointers to #GDBusSignalInfo structures or %NULL if there are no signals.</doc> + <array c:type="GDBusSignalInfo**"> + <type name="DBusSignalInfo" c:type="GDBusSignalInfo*"/> + </array> + </field> + <field name="properties" writable="1"> + <doc xml:space="preserve">A pointer to a %NULL-terminated array of pointers to #GDBusPropertyInfo structures or %NULL if there are no properties.</doc> + <array c:type="GDBusPropertyInfo**"> + <type name="DBusPropertyInfo" c:type="GDBusPropertyInfo*"/> + </array> + </field> + <field name="annotations" writable="1"> + <doc xml:space="preserve">A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.</doc> + <array c:type="GDBusAnnotationInfo**"> + <type name="DBusAnnotationInfo" c:type="GDBusAnnotationInfo*"/> + </array> + </field> + <method name="cache_build" c:identifier="g_dbus_interface_info_cache_build" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceInfo.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="cache_release" c:identifier="g_dbus_interface_info_cache_release" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A GDBusInterfaceInfo</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="generate_xml" c:identifier="g_dbus_interface_info_generate_xml" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusNodeInfo</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </instance-parameter> + <parameter name="indent" transfer-ownership="none"> + <doc xml:space="preserve">Indentation level.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="string_builder" transfer-ownership="none"> + <doc xml:space="preserve">A #GString to to append XML data to.</doc> + <type name="GLib.String" c:type="GString*"/> + </parameter> + </parameters> + </method> + <method name="lookup_method" c:identifier="g_dbus_interface_info_lookup_method" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info.</doc> + <type name="DBusMethodInfo" c:type="GDBusMethodInfo*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceInfo.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus method name (typically in CamelCase)</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="lookup_property" c:identifier="g_dbus_interface_info_lookup_property" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info.</doc> + <type name="DBusPropertyInfo" c:type="GDBusPropertyInfo*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceInfo.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus property name (typically in CamelCase).</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="lookup_signal" c:identifier="g_dbus_interface_info_lookup_signal" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info.</doc> + <type name="DBusSignalInfo" c:type="GDBusSignalInfo*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceInfo.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus signal name (typically in CamelCase)</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_dbus_interface_info_ref" version="2.26"> + <doc xml:space="preserve">If @info is statically allocated does nothing. Otherwise increases +the reference count.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">The same @info.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceInfo</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_dbus_interface_info_unref" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceInfo.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </instance-parameter> + </parameters> + </method> + </record> + <callback name="DBusInterfaceMethodCallFunc" c:type="GDBusInterfaceMethodCallFunc" version="2.26"> + <doc xml:space="preserve">The type of the @method_call function in #GDBusInterfaceVTable.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="sender" transfer-ownership="none"> + <doc xml:space="preserve">The unique bus name of the remote caller.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">The object path that the method was invoked on.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">The D-Bus interface name the method was invoked on.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="method_name" transfer-ownership="none"> + <doc xml:space="preserve">The name of the method that was invoked.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none"> + <doc xml:space="preserve">A #GVariant tuple with parameters.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="invocation" transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusMethodInvocation object that must be used to return a value or error.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="7"> + <doc xml:space="preserve">The @user_data #gpointer passed to g_dbus_connection_register_object().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="DBusInterfaceSetPropertyFunc" c:type="GDBusInterfaceSetPropertyFunc" version="2.26"> + <doc xml:space="preserve">The type of the @set_property function in #GDBusInterfaceVTable.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the property was set to @value, %FALSE if @error is set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="sender" transfer-ownership="none"> + <doc xml:space="preserve">The unique bus name of the remote caller.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">The object path that the method was invoked on.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">The D-Bus interface name for the property.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="property_name" transfer-ownership="none"> + <doc xml:space="preserve">The name of the property to get the value of.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">The value to set the property to.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">Return location for error.</doc> + <type name="GLib.Error" c:type="GError**"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="7"> + <doc xml:space="preserve">The @user_data #gpointer passed to g_dbus_connection_register_object().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <class name="DBusInterfaceSkeleton" c:symbol-prefix="dbus_interface_skeleton" c:type="GDBusInterfaceSkeleton" version="2.30" parent="GObject.Object" abstract="1" glib:type-name="GDBusInterfaceSkeleton" glib:get-type="g_dbus_interface_skeleton_get_type" glib:type-struct="DBusInterfaceSkeletonClass"> + <doc xml:space="preserve">Abstract base class for D-Bus interfaces on the service side.</doc> + <implements name="DBusInterface"/> + <virtual-method name="flush" invoker="flush" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="g_authorize_method"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + <parameter name="invocation" transfer-ownership="none"> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_info" invoker="get_info" version="2.30"> + <doc xml:space="preserve">Gets D-Bus introspection information for the D-Bus interface +implemented by @interface_.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceInfo (never %NULL). Do not free.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_properties" invoker="get_properties" version="2.30"> + <doc xml:space="preserve">Gets all D-Bus properties for @interface_.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GVariant of type +['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. +Free with g_variant_unref().</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_vtable" invoker="get_vtable" version="2.30" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">A #GDBusInterfaceVTable (never %NULL).</doc> + <type name="DBusInterfaceVTable" c:type="GDBusInterfaceVTable*"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="export" c:identifier="g_dbus_interface_skeleton_export" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the interface was exported on @connection, otherwise %FALSE with +@error set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">The D-Bus interface to export.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection to export @interface_ on.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">The path to export the interface at.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="flush" c:identifier="g_dbus_interface_skeleton_flush" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_connection" c:identifier="g_dbus_interface_skeleton_get_connection" version="2.30"> + <doc xml:space="preserve">Gets the first connection that @interface_ is exported on, if any.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">A #GDBusConnection or %NULL if @interface_ is +not exported anywhere. Do not free, the object belongs to @interface_.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_connections" c:identifier="g_dbus_interface_skeleton_get_connections" version="2.32"> + <doc xml:space="preserve">Gets a list of the connections that @interface_ is exported on.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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().</doc> + <type name="GLib.List" c:type="GList*"> + <type name="DBusConnection"/> + </type> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_flags" c:identifier="g_dbus_interface_skeleton_get_flags" version="2.30"> + <doc xml:space="preserve">Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior +of @interface_</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">One or more flags from the #GDBusInterfaceSkeletonFlags enumeration.</doc> + <type name="DBusInterfaceSkeletonFlags" c:type="GDBusInterfaceSkeletonFlags"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_info" c:identifier="g_dbus_interface_skeleton_get_info" version="2.30"> + <doc xml:space="preserve">Gets D-Bus introspection information for the D-Bus interface +implemented by @interface_.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceInfo (never %NULL). Do not free.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_object_path" c:identifier="g_dbus_interface_skeleton_get_object_path" version="2.30"> + <doc xml:space="preserve">Gets the object path that @interface_ is exported on, if any.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">A string owned by @interface_ or %NULL if @interface_ is not exported +anywhere. Do not free, the string belongs to @interface_.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_properties" c:identifier="g_dbus_interface_skeleton_get_properties" version="2.30"> + <doc xml:space="preserve">Gets all D-Bus properties for @interface_.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GVariant of type +['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. +Free with g_variant_unref().</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_vtable" c:identifier="g_dbus_interface_skeleton_get_vtable" version="2.30" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value> + <doc xml:space="preserve">A #GDBusInterfaceVTable (never %NULL).</doc> + <type name="DBusInterfaceVTable" c:type="GDBusInterfaceVTable*"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + </parameters> + </method> + <method name="has_connection" c:identifier="g_dbus_interface_skeleton_has_connection" version="2.32"> + <doc xml:space="preserve">Checks if @interface_ is exported on @connection.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @interface_ is exported on @connection, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + </parameters> + </method> + <method name="set_flags" c:identifier="g_dbus_interface_skeleton_set_flags" version="2.30"> + <doc xml:space="preserve">Sets flags describing what the behavior of @skeleton should be.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GDBusInterfaceSkeletonFlags enumeration.</doc> + <type name="DBusInterfaceSkeletonFlags" c:type="GDBusInterfaceSkeletonFlags"/> + </parameter> + </parameters> + </method> + <method name="unexport" c:identifier="g_dbus_interface_skeleton_unexport" version="2.30"> + <doc xml:space="preserve">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()</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + </parameters> + </method> + <method name="unexport_from_connection" c:identifier="g_dbus_interface_skeleton_unexport_from_connection" version="2.32"> + <doc xml:space="preserve">Stops exporting @interface_ on @connection. + +To stop exporting on all connections the interface is exported on, +use g_dbus_interface_skeleton_unexport().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + </parameters> + </method> + <property name="g-flags" version="2.30" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GDBusInterfaceSkeletonFlags enumeration.</doc> + <type name="DBusInterfaceSkeletonFlags"/> + </property> + <field name="parent_instance" readable="0" private="1"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="DBusInterfaceSkeletonPrivate" c:type="GDBusInterfaceSkeletonPrivate*"/> + </field> + <glib:signal name="g-authorize-method" when="last" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the call is authorized, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="invocation" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="DBusInterfaceSkeletonClass" c:type="GDBusInterfaceSkeletonClass" glib:is-gtype-struct-for="DBusInterfaceSkeleton" version="2.30"> + <doc xml:space="preserve">Class structure for #GDBusInterfaceSkeleton.</doc> + <field name="parent_class"> + <doc xml:space="preserve">The parent class.</doc> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="get_info"> + <callback name="get_info"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceInfo (never %NULL). Do not free.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </return-value> + <parameters> + <parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_vtable" introspectable="0"> + <callback name="get_vtable" introspectable="0"> + <return-value> + <doc xml:space="preserve">A #GDBusInterfaceVTable (never %NULL).</doc> + <type name="DBusInterfaceVTable" c:type="GDBusInterfaceVTable*"/> + </return-value> + <parameters> + <parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_properties"> + <callback name="get_properties"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GVariant of type +['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. +Free with g_variant_unref().</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="flush"> + <callback name="flush"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="vfunc_padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="8"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + <field name="g_authorize_method"> + <callback name="g_authorize_method"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="interface_" transfer-ownership="none"> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </parameter> + <parameter name="invocation" transfer-ownership="none"> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="signal_padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="8"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <bitfield name="DBusInterfaceSkeletonFlags" version="2.30" glib:type-name="GDBusInterfaceSkeletonFlags" glib:get-type="g_dbus_interface_skeleton_flags_get_type" c:type="GDBusInterfaceSkeletonFlags"> + <doc xml:space="preserve">Flags describing the behavior of a #GDBusInterfaceSkeleton instance.</doc> + <member name="none" value="0" c:identifier="G_DBUS_INTERFACE_SKELETON_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="handle_method_invocations_in_thread" value="1" c:identifier="G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD" glib:nick="handle-method-invocations-in-thread"> + <doc xml:space="preserve">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.</doc> + </member> + </bitfield> + <record name="DBusInterfaceSkeletonPrivate" c:type="GDBusInterfaceSkeletonPrivate" disguised="1"/> + <record name="DBusInterfaceVTable" c:type="GDBusInterfaceVTable" version="2.26"> + <doc xml:space="preserve">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.</doc> + <field name="method_call" writable="1"> + <doc xml:space="preserve">Function for handling incoming method calls.</doc> + <type name="DBusInterfaceMethodCallFunc" c:type="GDBusInterfaceMethodCallFunc"/> + </field> + <field name="get_property" writable="1"> + <doc xml:space="preserve">Function for getting a property.</doc> + <type name="DBusInterfaceGetPropertyFunc" c:type="GDBusInterfaceGetPropertyFunc"/> + </field> + <field name="set_property" writable="1"> + <doc xml:space="preserve">Function for setting a property.</doc> + <type name="DBusInterfaceSetPropertyFunc" c:type="GDBusInterfaceSetPropertyFunc"/> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="8"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <class name="DBusMenuModel" c:symbol-prefix="dbus_menu_model" c:type="GDBusMenuModel" parent="MenuModel" glib:type-name="GDBusMenuModel" glib:get-type="g_dbus_menu_model_get_type"> + <doc xml:space="preserve">#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().</doc> + <function name="get" c:identifier="g_dbus_menu_model_get" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GDBusMenuModel object. Free with + g_object_unref().</doc> + <type name="DBusMenuModel" c:type="GDBusMenuModel*"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="bus_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the bus name which exports the menu model + or %NULL if @connection is not a message bus connection</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">the object path at which the menu model is exported</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + </class> + <class name="DBusMessage" c:symbol-prefix="dbus_message" c:type="GDBusMessage" version="2.26" parent="GObject.Object" glib:type-name="GDBusMessage" glib:get-type="g_dbus_message_get_type"> + <doc xml:space="preserve">A type for representing D-Bus messages that can be sent or received +on a #GDBusConnection.</doc> + <constructor name="new" c:identifier="g_dbus_message_new" version="2.26"> + <doc xml:space="preserve">Creates a new empty #GDBusMessage.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusMessage. Free with g_object_unref().</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </return-value> + </constructor> + <constructor name="new_from_blob" c:identifier="g_dbus_message_new_from_blob" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A new #GDBusMessage or %NULL if @error is set. Free with +g_object_unref().</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </return-value> + <parameters> + <parameter name="blob" transfer-ownership="none"> + <doc xml:space="preserve">A blob representing a binary D-Bus message.</doc> + <array length="1" zero-terminated="0" c:type="guchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="blob_len" transfer-ownership="none"> + <doc xml:space="preserve">The length of @blob.</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="capabilities" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusCapabilityFlags describing what protocol features are supported.</doc> + <type name="DBusCapabilityFlags" c:type="GDBusCapabilityFlags"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_method_call" c:identifier="g_dbus_message_new_method_call" version="2.26"> + <doc xml:space="preserve">Creates a new #GDBusMessage for a method call.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusMessage. Free with g_object_unref().</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A valid D-Bus name or %NULL.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">A valid object path.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A valid D-Bus interface name or %NULL.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="method" transfer-ownership="none"> + <doc xml:space="preserve">A valid method name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_signal" c:identifier="g_dbus_message_new_signal" version="2.26"> + <doc xml:space="preserve">Creates a new #GDBusMessage for a signal emission.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusMessage. Free with g_object_unref().</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </return-value> + <parameters> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">A valid object path.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A valid D-Bus interface name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="signal" transfer-ownership="none"> + <doc xml:space="preserve">A valid signal name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <function name="bytes_needed" c:identifier="g_dbus_message_bytes_needed" version="2.26" throws="1"> + <doc xml:space="preserve">Utility function to calculate how many bytes are needed to +completely deserialize the D-Bus message stored at @blob.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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).</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="blob" transfer-ownership="none"> + <doc xml:space="preserve">A blob representing a binary D-Bus message.</doc> + <array length="1" zero-terminated="0" c:type="guchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="blob_len" transfer-ownership="none"> + <doc xml:space="preserve">The length of @blob (must be at least 16).</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </function> + <method name="copy" c:identifier="g_dbus_message_copy" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A new #GDBusMessage or %NULL if @error is set. + Free with g_object_unref().</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_arg0" c:identifier="g_dbus_message_get_arg0" version="2.26"> + <doc xml:space="preserve">Convenience to get the first item in the body of @message.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The string item or %NULL if the first item in the body of +@message is not a string.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_body" c:identifier="g_dbus_message_get_body" version="2.26"> + <doc xml:space="preserve">Gets the body of a message.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">A #GVariant or %NULL if the body is +empty. Do not free, it is owned by @message.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_byte_order" c:identifier="g_dbus_message_get_byte_order"> + <doc xml:space="preserve">Gets the byte order of @message.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The byte order.</doc> + <type name="DBusMessageByteOrder" c:type="GDBusMessageByteOrder"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_destination" c:identifier="g_dbus_message_get_destination" version="2.26"> + <doc xml:space="preserve">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The value.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_error_name" c:identifier="g_dbus_message_get_error_name" version="2.26"> + <doc xml:space="preserve">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The value.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_flags" c:identifier="g_dbus_message_get_flags" version="2.26"> + <doc xml:space="preserve">Gets the flags for @message.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).</doc> + <type name="DBusMessageFlags" c:type="GDBusMessageFlags"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_header" c:identifier="g_dbus_message_get_header" version="2.26"> + <doc xml:space="preserve">Gets a header field on @message. + +The caller is responsible for checking the type of the returned #GVariant +matches what is expected.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">A #GVariant with the value if the header was found, %NULL +otherwise. Do not free, it is owned by @message.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="header_field" transfer-ownership="none"> + <doc xml:space="preserve">A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)</doc> + <type name="DBusMessageHeaderField" c:type="GDBusMessageHeaderField"/> + </parameter> + </parameters> + </method> + <method name="get_header_fields" c:identifier="g_dbus_message_get_header_fields" version="2.26"> + <doc xml:space="preserve">Gets an array of all header fields on @message that are set.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">An array of header fields +terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element +is a #guchar. Free with g_free().</doc> + <array c:type="guchar*"> + <type name="guint8" c:type="guchar"/> + </array> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_interface" c:identifier="g_dbus_message_get_interface" version="2.26"> + <doc xml:space="preserve">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The value.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_locked" c:identifier="g_dbus_message_get_locked" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @message is locked, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_member" c:identifier="g_dbus_message_get_member" version="2.26"> + <doc xml:space="preserve">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The value.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_message_type" c:identifier="g_dbus_message_get_message_type" version="2.26"> + <doc xml:space="preserve">Gets the type of @message.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).</doc> + <type name="DBusMessageType" c:type="GDBusMessageType"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_num_unix_fds" c:identifier="g_dbus_message_get_num_unix_fds" version="2.26"> + <doc xml:space="preserve">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The value.</doc> + <type name="guint32" c:type="guint32"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_path" c:identifier="g_dbus_message_get_path" version="2.26"> + <doc xml:space="preserve">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The value.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_reply_serial" c:identifier="g_dbus_message_get_reply_serial" version="2.26"> + <doc xml:space="preserve">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The value.</doc> + <type name="guint32" c:type="guint32"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_sender" c:identifier="g_dbus_message_get_sender" version="2.26"> + <doc xml:space="preserve">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The value.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_serial" c:identifier="g_dbus_message_get_serial" version="2.26"> + <doc xml:space="preserve">Gets the serial for @message.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A #guint32.</doc> + <type name="guint32" c:type="guint32"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_signature" c:identifier="g_dbus_message_get_signature" version="2.26"> + <doc xml:space="preserve">Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The value.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_unix_fd_list" c:identifier="g_dbus_message_get_unix_fd_list" version="2.26"> + <doc xml:space="preserve">Gets the UNIX file descriptors associated with @message, if any. + +This method is only available on UNIX. + +The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE +values in the body of the message. For example, +if g_variant_get_handle() returns 5, that is intended to be a reference +to the file descriptor that can be accessed by +`g_unix_fd_list_get (list, 5, ...)`.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">A #GUnixFDList or %NULL if no file descriptors are +associated. Do not free, this object is owned by @message.</doc> + <type name="UnixFDList" c:type="GUnixFDList*"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="lock" c:identifier="g_dbus_message_lock" version="2.26"> + <doc xml:space="preserve">If @message is locked, does nothing. Otherwise locks the message.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="new_method_error" c:identifier="g_dbus_message_new_method_error" version="2.26" introspectable="0"> + <doc xml:space="preserve">Creates a new #GDBusMessage that is an error reply to @method_call_message.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusMessage. Free with g_object_unref().</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </return-value> + <parameters> + <instance-parameter name="method_call_message" transfer-ownership="none"> + <doc xml:space="preserve">A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to +create a reply message to.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="error_name" transfer-ownership="none"> + <doc xml:space="preserve">A valid D-Bus error name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="error_message_format" transfer-ownership="none"> + <doc xml:space="preserve">The D-Bus error message in a printf() format.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">Arguments for @error_message_format.</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="new_method_error_literal" c:identifier="g_dbus_message_new_method_error_literal" version="2.26"> + <doc xml:space="preserve">Creates a new #GDBusMessage that is an error reply to @method_call_message.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusMessage. Free with g_object_unref().</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </return-value> + <parameters> + <instance-parameter name="method_call_message" transfer-ownership="none"> + <doc xml:space="preserve">A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to +create a reply message to.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="error_name" transfer-ownership="none"> + <doc xml:space="preserve">A valid D-Bus error name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="error_message" transfer-ownership="none"> + <doc xml:space="preserve">The D-Bus error message.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="new_method_error_valist" c:identifier="g_dbus_message_new_method_error_valist" version="2.26" introspectable="0"> + <doc xml:space="preserve">Like g_dbus_message_new_method_error() but intended for language bindings.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusMessage. Free with g_object_unref().</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </return-value> + <parameters> + <instance-parameter name="method_call_message" transfer-ownership="none"> + <doc xml:space="preserve">A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to +create a reply message to.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="error_name" transfer-ownership="none"> + <doc xml:space="preserve">A valid D-Bus error name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="error_message_format" transfer-ownership="none"> + <doc xml:space="preserve">The D-Bus error message in a printf() format.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="var_args" transfer-ownership="none"> + <doc xml:space="preserve">Arguments for @error_message_format.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </method> + <method name="new_method_reply" c:identifier="g_dbus_message_new_method_reply" version="2.26"> + <doc xml:space="preserve">Creates a new #GDBusMessage that is a reply to @method_call_message.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GDBusMessage. Free with g_object_unref().</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </return-value> + <parameters> + <instance-parameter name="method_call_message" transfer-ownership="none"> + <doc xml:space="preserve">A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to +create a reply message to.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="print" c:identifier="g_dbus_message_print" version="2.26"> + <doc xml:space="preserve">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 +]|</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A string that should be freed with g_free().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="indent" transfer-ownership="none"> + <doc xml:space="preserve">Indentation level.</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="set_body" c:identifier="g_dbus_message_set_body" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="body" transfer-ownership="none"> + <doc xml:space="preserve">Either %NULL or a #GVariant that is a tuple.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="set_byte_order" c:identifier="g_dbus_message_set_byte_order"> + <doc xml:space="preserve">Sets the byte order of @message.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="byte_order" transfer-ownership="none"> + <doc xml:space="preserve">The byte order.</doc> + <type name="DBusMessageByteOrder" c:type="GDBusMessageByteOrder"/> + </parameter> + </parameters> + </method> + <method name="set_destination" c:identifier="g_dbus_message_set_destination" version="2.26"> + <doc xml:space="preserve">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The value to set.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_error_name" c:identifier="g_dbus_message_set_error_name" version="2.26"> + <doc xml:space="preserve">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">The value to set.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_flags" c:identifier="g_dbus_message_set_flags" version="2.26"> + <doc xml:space="preserve">Sets the flags to set on @message.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags for @message that are set (typically values from the #GDBusMessageFlags +enumeration bitwise ORed together).</doc> + <type name="DBusMessageFlags" c:type="GDBusMessageFlags"/> + </parameter> + </parameters> + </method> + <method name="set_header" c:identifier="g_dbus_message_set_header" version="2.26"> + <doc xml:space="preserve">Sets a header field on @message. + +If @value is floating, @message assumes ownership of @value.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="header_field" transfer-ownership="none"> + <doc xml:space="preserve">A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)</doc> + <type name="DBusMessageHeaderField" c:type="GDBusMessageHeaderField"/> + </parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GVariant to set the header field or %NULL to clear the header field.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="set_interface" c:identifier="g_dbus_message_set_interface" version="2.26"> + <doc xml:space="preserve">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The value to set.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_member" c:identifier="g_dbus_message_set_member" version="2.26"> + <doc xml:space="preserve">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The value to set.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_message_type" c:identifier="g_dbus_message_set_message_type" version="2.26"> + <doc xml:space="preserve">Sets @message to be of @type.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).</doc> + <type name="DBusMessageType" c:type="GDBusMessageType"/> + </parameter> + </parameters> + </method> + <method name="set_num_unix_fds" c:identifier="g_dbus_message_set_num_unix_fds" version="2.26"> + <doc xml:space="preserve">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">The value to set.</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + </parameters> + </method> + <method name="set_path" c:identifier="g_dbus_message_set_path" version="2.26"> + <doc xml:space="preserve">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The value to set.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_reply_serial" c:identifier="g_dbus_message_set_reply_serial" version="2.26"> + <doc xml:space="preserve">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">The value to set.</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + </parameters> + </method> + <method name="set_sender" c:identifier="g_dbus_message_set_sender" version="2.26"> + <doc xml:space="preserve">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The value to set.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_serial" c:identifier="g_dbus_message_set_serial" version="2.26"> + <doc xml:space="preserve">Sets the serial for @message.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="serial" transfer-ownership="none"> + <doc xml:space="preserve">A #guint32.</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + </parameters> + </method> + <method name="set_signature" c:identifier="g_dbus_message_set_signature" version="2.26"> + <doc xml:space="preserve">Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The value to set.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_unix_fd_list" c:identifier="g_dbus_message_set_unix_fd_list" version="2.26"> + <doc xml:space="preserve">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. + +When designing D-Bus APIs that are intended to be interoperable, +please note that non-GDBus implementations of D-Bus can usually only +access file descriptors if they are referenced by a value of type +%G_VARIANT_TYPE_HANDLE in the body of the message.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="fd_list" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GUnixFDList or %NULL.</doc> + <type name="UnixFDList" c:type="GUnixFDList*"/> + </parameter> + </parameters> + </method> + <method name="to_blob" c:identifier="g_dbus_message_to_blob" version="2.26" throws="1"> + <doc xml:space="preserve">Serializes @message to a blob. The byte order returned by +g_dbus_message_get_byte_order() will be used.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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().</doc> + <array length="0" zero-terminated="0" c:type="guchar*"> + <type name="guint8" c:type="guchar"/> + </array> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + <parameter name="out_size" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">Return location for size of generated blob.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="capabilities" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusCapabilityFlags describing what protocol features are supported.</doc> + <type name="DBusCapabilityFlags" c:type="GDBusCapabilityFlags"/> + </parameter> + </parameters> + </method> + <method name="to_gerror" c:identifier="g_dbus_message_to_gerror" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @error was set, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMessage.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </instance-parameter> + </parameters> + </method> + <property name="locked" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </property> + </class> + <enumeration name="DBusMessageByteOrder" version="2.26" glib:type-name="GDBusMessageByteOrder" glib:get-type="g_dbus_message_byte_order_get_type" c:type="GDBusMessageByteOrder"> + <doc xml:space="preserve">Enumeration used to describe the byte order of a D-Bus message.</doc> + <member name="big_endian" value="66" c:identifier="G_DBUS_MESSAGE_BYTE_ORDER_BIG_ENDIAN" glib:nick="big-endian"> + <doc xml:space="preserve">The byte order is big endian.</doc> + </member> + <member name="little_endian" value="108" c:identifier="G_DBUS_MESSAGE_BYTE_ORDER_LITTLE_ENDIAN" glib:nick="little-endian"> + <doc xml:space="preserve">The byte order is little endian.</doc> + </member> + </enumeration> + <callback name="DBusMessageFilterFunction" c:type="GDBusMessageFilterFunction" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="message" transfer-ownership="full"> + <doc xml:space="preserve">A locked #GDBusMessage that the filter function takes ownership of.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </parameter> + <parameter name="incoming" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if it is a message received from the other peer, %FALSE if it is +a message to be sent to the other peer.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">User data passed when adding the filter.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <bitfield name="DBusMessageFlags" version="2.26" glib:type-name="GDBusMessageFlags" glib:get-type="g_dbus_message_flags_get_type" c:type="GDBusMessageFlags"> + <doc xml:space="preserve">Message flags used in #GDBusMessage.</doc> + <member name="none" value="0" c:identifier="G_DBUS_MESSAGE_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="no_reply_expected" value="1" c:identifier="G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED" glib:nick="no-reply-expected"> + <doc xml:space="preserve">A reply is not expected.</doc> + </member> + <member name="no_auto_start" value="2" c:identifier="G_DBUS_MESSAGE_FLAGS_NO_AUTO_START" glib:nick="no-auto-start"> + <doc xml:space="preserve">The bus must not launch an +owner for the destination name in response to this message.</doc> + </member> + <member name="allow_interactive_authorization" value="4" c:identifier="G_DBUS_MESSAGE_FLAGS_ALLOW_INTERACTIVE_AUTHORIZATION" glib:nick="allow-interactive-authorization"> + <doc xml:space="preserve">If set on a method +call, this flag means that the caller is prepared to wait for interactive +authorization. Since 2.46.</doc> + </member> + </bitfield> + <enumeration name="DBusMessageHeaderField" version="2.26" glib:type-name="GDBusMessageHeaderField" glib:get-type="g_dbus_message_header_field_get_type" c:type="GDBusMessageHeaderField"> + <doc xml:space="preserve">Header fields used in #GDBusMessage.</doc> + <member name="invalid" value="0" c:identifier="G_DBUS_MESSAGE_HEADER_FIELD_INVALID" glib:nick="invalid"> + <doc xml:space="preserve">Not a valid header field.</doc> + </member> + <member name="path" value="1" c:identifier="G_DBUS_MESSAGE_HEADER_FIELD_PATH" glib:nick="path"> + <doc xml:space="preserve">The object path.</doc> + </member> + <member name="interface" value="2" c:identifier="G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE" glib:nick="interface"> + <doc xml:space="preserve">The interface name.</doc> + </member> + <member name="member" value="3" c:identifier="G_DBUS_MESSAGE_HEADER_FIELD_MEMBER" glib:nick="member"> + <doc xml:space="preserve">The method or signal name.</doc> + </member> + <member name="error_name" value="4" c:identifier="G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME" glib:nick="error-name"> + <doc xml:space="preserve">The name of the error that occurred.</doc> + </member> + <member name="reply_serial" value="5" c:identifier="G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL" glib:nick="reply-serial"> + <doc xml:space="preserve">The serial number the message is a reply to.</doc> + </member> + <member name="destination" value="6" c:identifier="G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION" glib:nick="destination"> + <doc xml:space="preserve">The name the message is intended for.</doc> + </member> + <member name="sender" value="7" c:identifier="G_DBUS_MESSAGE_HEADER_FIELD_SENDER" glib:nick="sender"> + <doc xml:space="preserve">Unique name of the sender of the message (filled in by the bus).</doc> + </member> + <member name="signature" value="8" c:identifier="G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE" glib:nick="signature"> + <doc xml:space="preserve">The signature of the message body.</doc> + </member> + <member name="num_unix_fds" value="9" c:identifier="G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS" glib:nick="num-unix-fds"> + <doc xml:space="preserve">The number of UNIX file descriptors that accompany the message.</doc> + </member> + </enumeration> + <enumeration name="DBusMessageType" version="2.26" glib:type-name="GDBusMessageType" glib:get-type="g_dbus_message_type_get_type" c:type="GDBusMessageType"> + <doc xml:space="preserve">Message types used in #GDBusMessage.</doc> + <member name="invalid" value="0" c:identifier="G_DBUS_MESSAGE_TYPE_INVALID" glib:nick="invalid"> + <doc xml:space="preserve">Message is of invalid type.</doc> + </member> + <member name="method_call" value="1" c:identifier="G_DBUS_MESSAGE_TYPE_METHOD_CALL" glib:nick="method-call"> + <doc xml:space="preserve">Method call.</doc> + </member> + <member name="method_return" value="2" c:identifier="G_DBUS_MESSAGE_TYPE_METHOD_RETURN" glib:nick="method-return"> + <doc xml:space="preserve">Method reply.</doc> + </member> + <member name="error" value="3" c:identifier="G_DBUS_MESSAGE_TYPE_ERROR" glib:nick="error"> + <doc xml:space="preserve">Error reply.</doc> + </member> + <member name="signal" value="4" c:identifier="G_DBUS_MESSAGE_TYPE_SIGNAL" glib:nick="signal"> + <doc xml:space="preserve">Signal emission.</doc> + </member> + </enumeration> + <record name="DBusMethodInfo" c:type="GDBusMethodInfo" version="2.26" glib:type-name="GDBusMethodInfo" glib:get-type="g_dbus_method_info_get_type" c:symbol-prefix="dbus_method_info"> + <doc xml:space="preserve">Information about a method on an D-Bus interface.</doc> + <field name="ref_count" writable="1"> + <doc xml:space="preserve">The reference count or -1 if statically allocated.</doc> + <type name="gint" c:type="volatile gint"/> + </field> + <field name="name" writable="1"> + <doc xml:space="preserve">The name of the D-Bus method, e.g. @RequestName.</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="in_args" writable="1"> + <doc xml:space="preserve">A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no in arguments.</doc> + <array c:type="GDBusArgInfo**"> + <type name="DBusArgInfo" c:type="GDBusArgInfo*"/> + </array> + </field> + <field name="out_args" writable="1"> + <doc xml:space="preserve">A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no out arguments.</doc> + <array c:type="GDBusArgInfo**"> + <type name="DBusArgInfo" c:type="GDBusArgInfo*"/> + </array> + </field> + <field name="annotations" writable="1"> + <doc xml:space="preserve">A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.</doc> + <array c:type="GDBusAnnotationInfo**"> + <type name="DBusAnnotationInfo" c:type="GDBusAnnotationInfo*"/> + </array> + </field> + <method name="ref" c:identifier="g_dbus_method_info_ref" version="2.26"> + <doc xml:space="preserve">If @info is statically allocated does nothing. Otherwise increases +the reference count.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">The same @info.</doc> + <type name="DBusMethodInfo" c:type="GDBusMethodInfo*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMethodInfo</doc> + <type name="DBusMethodInfo" c:type="GDBusMethodInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_dbus_method_info_unref" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMethodInfo.</doc> + <type name="DBusMethodInfo" c:type="GDBusMethodInfo*"/> + </instance-parameter> + </parameters> + </method> + </record> + <class name="DBusMethodInvocation" c:symbol-prefix="dbus_method_invocation" c:type="GDBusMethodInvocation" version="2.26" parent="GObject.Object" glib:type-name="GDBusMethodInvocation" glib:get-type="g_dbus_method_invocation_get_type"> + <doc xml:space="preserve">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().</doc> + <method name="get_connection" c:identifier="g_dbus_method_invocation_get_connection" version="2.26"> + <doc xml:space="preserve">Gets the #GDBusConnection the method was invoked on.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection. Do not free, it is owned by @invocation.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_interface_name" c:identifier="g_dbus_method_invocation_get_interface_name" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A string. Do not free, it is owned by @invocation.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_message" c:identifier="g_dbus_method_invocation_get_message" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">#GDBusMessage. Do not free, it is owned by @invocation.</doc> + <type name="DBusMessage" c:type="GDBusMessage*"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_method_info" c:identifier="g_dbus_method_invocation_get_method_info" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation.</doc> + <type name="DBusMethodInfo" c:type="const GDBusMethodInfo*"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_method_name" c:identifier="g_dbus_method_invocation_get_method_name" version="2.26"> + <doc xml:space="preserve">Gets the name of the method that was invoked.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A string. Do not free, it is owned by @invocation.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_object_path" c:identifier="g_dbus_method_invocation_get_object_path" version="2.26"> + <doc xml:space="preserve">Gets the object path the method was invoked on.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A string. Do not free, it is owned by @invocation.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_parameters" c:identifier="g_dbus_method_invocation_get_parameters" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A #GVariant tuple. Do not unref this because it is owned by @invocation.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_property_info" c:identifier="g_dbus_method_invocation_get_property_info" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a #GDBusPropertyInfo or %NULL</doc> + <type name="DBusPropertyInfo" c:type="const GDBusPropertyInfo*"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMethodInvocation</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_sender" c:identifier="g_dbus_method_invocation_get_sender" version="2.26"> + <doc xml:space="preserve">Gets the bus name that invoked the method.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A string. Do not free, it is owned by @invocation.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_user_data" c:identifier="g_dbus_method_invocation_get_user_data" version="2.26" introspectable="0"> + <doc xml:space="preserve">Gets the @user_data #gpointer passed to g_dbus_connection_register_object().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">A #gpointer.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + </parameters> + </method> + <method name="return_dbus_error" c:identifier="g_dbus_method_invocation_return_dbus_error" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + <parameter name="error_name" transfer-ownership="none"> + <doc xml:space="preserve">A valid D-Bus error name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="error_message" transfer-ownership="none"> + <doc xml:space="preserve">A valid D-Bus error message.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="return_error" c:identifier="g_dbus_method_invocation_return_error" version="2.26" introspectable="0"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">A #GQuark for the #GError error domain.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="code" transfer-ownership="none"> + <doc xml:space="preserve">The error code.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">printf()-style format.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">Parameters for @format.</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="return_error_literal" c:identifier="g_dbus_method_invocation_return_error_literal" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">A #GQuark for the #GError error domain.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="code" transfer-ownership="none"> + <doc xml:space="preserve">The error code.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">The error message.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="return_error_valist" c:identifier="g_dbus_method_invocation_return_error_valist" version="2.26" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">A #GQuark for the #GError error domain.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="code" transfer-ownership="none"> + <doc xml:space="preserve">The error code.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">printf()-style format.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="var_args" transfer-ownership="none"> + <doc xml:space="preserve">#va_list of parameters for @format.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </method> + <method name="return_gerror" c:identifier="g_dbus_method_invocation_return_gerror" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">A #GError.</doc> + <type name="GLib.Error" c:type="const GError*"/> + </parameter> + </parameters> + </method> + <method name="return_value" c:identifier="g_dbus_method_invocation_return_value" version="2.26"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + <parameter name="parameters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="return_value_with_unix_fd_list" c:identifier="g_dbus_method_invocation_return_value_with_unix_fd_list" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + <parameter name="parameters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="fd_list" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GUnixFDList or %NULL.</doc> + <type name="UnixFDList" c:type="GUnixFDList*"/> + </parameter> + </parameters> + </method> + <method name="take_error" c:identifier="g_dbus_method_invocation_take_error" version="2.30" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="invocation" transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </instance-parameter> + <parameter name="error" transfer-ownership="full"> + <doc xml:space="preserve">A #GError.</doc> + <type name="GLib.Error" c:type="GError*"/> + </parameter> + </parameters> + </method> + </class> + <record name="DBusNodeInfo" c:type="GDBusNodeInfo" version="2.26" glib:type-name="GDBusNodeInfo" glib:get-type="g_dbus_node_info_get_type" c:symbol-prefix="dbus_node_info"> + <doc xml:space="preserve">Information about nodes in a remote object hierarchy.</doc> + <field name="ref_count" writable="1"> + <doc xml:space="preserve">The reference count or -1 if statically allocated.</doc> + <type name="gint" c:type="volatile gint"/> + </field> + <field name="path" writable="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="interfaces" writable="1"> + <doc xml:space="preserve">A pointer to a %NULL-terminated array of pointers to #GDBusInterfaceInfo structures or %NULL if there are no interfaces.</doc> + <array c:type="GDBusInterfaceInfo**"> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </array> + </field> + <field name="nodes" writable="1"> + <doc xml:space="preserve">A pointer to a %NULL-terminated array of pointers to #GDBusNodeInfo structures or %NULL if there are no nodes.</doc> + <array c:type="GDBusNodeInfo**"> + <type name="DBusNodeInfo" c:type="GDBusNodeInfo*"/> + </array> + </field> + <field name="annotations" writable="1"> + <doc xml:space="preserve">A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.</doc> + <array c:type="GDBusAnnotationInfo**"> + <type name="DBusAnnotationInfo" c:type="GDBusAnnotationInfo*"/> + </array> + </field> + <constructor name="new_for_xml" c:identifier="g_dbus_node_info_new_for_xml" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusNodeInfo structure or %NULL if @error is set. Free +with g_dbus_node_info_unref().</doc> + <type name="DBusNodeInfo" c:type="GDBusNodeInfo*"/> + </return-value> + <parameters> + <parameter name="xml_data" transfer-ownership="none"> + <doc xml:space="preserve">Valid D-Bus introspection XML.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <method name="generate_xml" c:identifier="g_dbus_node_info_generate_xml" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusNodeInfo.</doc> + <type name="DBusNodeInfo" c:type="GDBusNodeInfo*"/> + </instance-parameter> + <parameter name="indent" transfer-ownership="none"> + <doc xml:space="preserve">Indentation level.</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="string_builder" transfer-ownership="none"> + <doc xml:space="preserve">A #GString to to append XML data to.</doc> + <type name="GLib.String" c:type="GString*"/> + </parameter> + </parameters> + </method> + <method name="lookup_interface" c:identifier="g_dbus_node_info_lookup_interface" version="2.26"> + <doc xml:space="preserve">Looks up information about an interface. + +The cost of this function is O(n) in number of interfaces.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusNodeInfo.</doc> + <type name="DBusNodeInfo" c:type="GDBusNodeInfo*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus interface name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_dbus_node_info_ref" version="2.26"> + <doc xml:space="preserve">If @info is statically allocated does nothing. Otherwise increases +the reference count.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">The same @info.</doc> + <type name="DBusNodeInfo" c:type="GDBusNodeInfo*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusNodeInfo</doc> + <type name="DBusNodeInfo" c:type="GDBusNodeInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_dbus_node_info_unref" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusNodeInfo.</doc> + <type name="DBusNodeInfo" c:type="GDBusNodeInfo*"/> + </instance-parameter> + </parameters> + </method> + </record> + <interface name="DBusObject" c:symbol-prefix="dbus_object" c:type="GDBusObject" glib:type-name="GDBusObject" glib:get-type="g_dbus_object_get_type" glib:type-struct="DBusObjectIface"> + <doc xml:space="preserve">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.</doc> + <virtual-method name="get_interface" invoker="get_interface" version="2.30"> + <doc xml:space="preserve">Gets the D-Bus interface with name @interface_name associated with +@object, if any.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">%NULL if not found, otherwise a + #GDBusInterface that must be freed with g_object_unref().</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObject.</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </instance-parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus interface name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_interfaces" invoker="get_interfaces" version="2.30"> + <doc xml:space="preserve">Gets the D-Bus interfaces associated with @object.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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().</doc> + <type name="GLib.List" c:type="GList*"> + <type name="DBusInterface"/> + </type> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObject.</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_object_path" invoker="get_object_path" version="2.30"> + <doc xml:space="preserve">Gets the object path for @object.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A string owned by @object. Do not free.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObject.</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="interface_added"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <type name="DBusObject" c:type="GDBusObject*"/> + </instance-parameter> + <parameter name="interface_" transfer-ownership="none"> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="interface_removed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <type name="DBusObject" c:type="GDBusObject*"/> + </instance-parameter> + <parameter name="interface_" transfer-ownership="none"> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_interface" c:identifier="g_dbus_object_get_interface" version="2.30"> + <doc xml:space="preserve">Gets the D-Bus interface with name @interface_name associated with +@object, if any.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">%NULL if not found, otherwise a + #GDBusInterface that must be freed with g_object_unref().</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObject.</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </instance-parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus interface name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_interfaces" c:identifier="g_dbus_object_get_interfaces" version="2.30"> + <doc xml:space="preserve">Gets the D-Bus interfaces associated with @object.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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().</doc> + <type name="GLib.List" c:type="GList*"> + <type name="DBusInterface"/> + </type> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObject.</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_object_path" c:identifier="g_dbus_object_get_object_path" version="2.30"> + <doc xml:space="preserve">Gets the object path for @object.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A string owned by @object. Do not free.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObject.</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </instance-parameter> + </parameters> + </method> + <glib:signal name="interface-added" when="last" version="2.30"> + <doc xml:space="preserve">Emitted when @interface is added to @object.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="interface" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusInterface that was added.</doc> + <type name="DBusInterface"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="interface-removed" when="last" version="2.30"> + <doc xml:space="preserve">Emitted when @interface is removed from @object.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="interface" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusInterface that was removed.</doc> + <type name="DBusInterface"/> + </parameter> + </parameters> + </glib:signal> + </interface> + <record name="DBusObjectIface" c:type="GDBusObjectIface" glib:is-gtype-struct-for="DBusObject" version="2.30"> + <doc xml:space="preserve">Base object type for D-Bus objects.</doc> + <field name="parent_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="get_object_path"> + <callback name="get_object_path"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A string owned by @object. Do not free.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObject.</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_interfaces"> + <callback name="get_interfaces"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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().</doc> + <type name="GLib.List" c:type="GList*"> + <type name="DBusInterface"/> + </type> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObject.</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_interface"> + <callback name="get_interface"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">%NULL if not found, otherwise a + #GDBusInterface that must be freed with g_object_unref().</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObject.</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus interface name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="interface_added"> + <callback name="interface_added"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <type name="DBusObject" c:type="GDBusObject*"/> + </parameter> + <parameter name="interface_" transfer-ownership="none"> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="interface_removed"> + <callback name="interface_removed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <type name="DBusObject" c:type="GDBusObject*"/> + </parameter> + <parameter name="interface_" transfer-ownership="none"> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <interface name="DBusObjectManager" c:symbol-prefix="dbus_object_manager" c:type="GDBusObjectManager" glib:type-name="GDBusObjectManager" glib:get-type="g_dbus_object_manager_get_type" glib:type-struct="DBusObjectManagerIface"> + <doc xml:space="preserve">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.</doc> + <virtual-method name="get_interface" invoker="get_interface" version="2.30"> + <doc xml:space="preserve">Gets the interface proxy for @interface_name at @object_path, if +any.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusInterface instance or %NULL. Free + with g_object_unref().</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManager.</doc> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </instance-parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">Object path to look up.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">D-Bus interface name to look up.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_object" invoker="get_object" version="2.30"> + <doc xml:space="preserve">Gets the #GDBusObjectProxy at @object_path, if any.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusObject or %NULL. Free with + g_object_unref().</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManager.</doc> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </instance-parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">Object path to look up.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_object_path" invoker="get_object_path" version="2.30"> + <doc xml:space="preserve">Gets the object path that @manager is for.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A string owned by @manager. Do not free.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManager.</doc> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_objects" invoker="get_objects" version="2.30"> + <doc xml:space="preserve">Gets all #GDBusObject objects known to @manager.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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().</doc> + <type name="GLib.List" c:type="GList*"> + <type name="DBusObject"/> + </type> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManager.</doc> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="interface_added"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </instance-parameter> + <parameter name="object" transfer-ownership="none"> + <type name="DBusObject" c:type="GDBusObject*"/> + </parameter> + <parameter name="interface_" transfer-ownership="none"> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="interface_removed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </instance-parameter> + <parameter name="object" transfer-ownership="none"> + <type name="DBusObject" c:type="GDBusObject*"/> + </parameter> + <parameter name="interface_" transfer-ownership="none"> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="object_added"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </instance-parameter> + <parameter name="object" transfer-ownership="none"> + <type name="DBusObject" c:type="GDBusObject*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="object_removed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </instance-parameter> + <parameter name="object" transfer-ownership="none"> + <type name="DBusObject" c:type="GDBusObject*"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_interface" c:identifier="g_dbus_object_manager_get_interface" version="2.30"> + <doc xml:space="preserve">Gets the interface proxy for @interface_name at @object_path, if +any.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusInterface instance or %NULL. Free + with g_object_unref().</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManager.</doc> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </instance-parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">Object path to look up.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">D-Bus interface name to look up.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_object" c:identifier="g_dbus_object_manager_get_object" version="2.30"> + <doc xml:space="preserve">Gets the #GDBusObjectProxy at @object_path, if any.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusObject or %NULL. Free with + g_object_unref().</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManager.</doc> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </instance-parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">Object path to look up.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_object_path" c:identifier="g_dbus_object_manager_get_object_path" version="2.30"> + <doc xml:space="preserve">Gets the object path that @manager is for.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A string owned by @manager. Do not free.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManager.</doc> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_objects" c:identifier="g_dbus_object_manager_get_objects" version="2.30"> + <doc xml:space="preserve">Gets all #GDBusObject objects known to @manager.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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().</doc> + <type name="GLib.List" c:type="GList*"> + <type name="DBusObject"/> + </type> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManager.</doc> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </instance-parameter> + </parameters> + </method> + <glib:signal name="interface-added" when="last" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusObject on which an interface was added.</doc> + <type name="DBusObject"/> + </parameter> + <parameter name="interface" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusInterface that was added.</doc> + <type name="DBusInterface"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="interface-removed" when="last" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusObject on which an interface was removed.</doc> + <type name="DBusObject"/> + </parameter> + <parameter name="interface" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusInterface that was removed.</doc> + <type name="DBusInterface"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="object-added" when="last" version="2.30"> + <doc xml:space="preserve">Emitted when @object is added to @manager.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusObject that was added.</doc> + <type name="DBusObject"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="object-removed" when="last" version="2.30"> + <doc xml:space="preserve">Emitted when @object is removed from @manager.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusObject that was removed.</doc> + <type name="DBusObject"/> + </parameter> + </parameters> + </glib:signal> + </interface> + <class name="DBusObjectManagerClient" c:symbol-prefix="dbus_object_manager_client" c:type="GDBusObjectManagerClient" version="2.30" parent="GObject.Object" glib:type-name="GDBusObjectManagerClient" glib:get-type="g_dbus_object_manager_client_get_type" glib:type-struct="DBusObjectManagerClientClass"> + <doc xml:space="preserve">#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.</doc> + <implements name="AsyncInitable"/> + <implements name="DBusObjectManager"/> + <implements name="Initable"/> + <constructor name="new_finish" c:identifier="g_dbus_object_manager_client_new_finish" version="2.30" throws="1"> + <doc xml:space="preserve">Finishes an operation started with g_dbus_object_manager_client_new().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A + #GDBusObjectManagerClient object or %NULL if @error is set. Free + with g_object_unref().</doc> + <type name="DBusObjectManagerClient" c:type="GDBusObjectManager*"/> + </return-value> + <parameters> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new().</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_for_bus_finish" c:identifier="g_dbus_object_manager_client_new_for_bus_finish" version="2.30" throws="1"> + <doc xml:space="preserve">Finishes an operation started with g_dbus_object_manager_client_new_for_bus().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A + #GDBusObjectManagerClient object or %NULL if @error is set. Free + with g_object_unref().</doc> + <type name="DBusObjectManagerClient" c:type="GDBusObjectManager*"/> + </return-value> + <parameters> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus().</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_for_bus_sync" c:identifier="g_dbus_object_manager_client_new_for_bus_sync" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A + #GDBusObjectManagerClient object or %NULL if @error is set. Free + with g_object_unref().</doc> + <type name="DBusObjectManagerClient" c:type="GDBusObjectManager*"/> + </return-value> + <parameters> + <parameter name="bus_type" transfer-ownership="none"> + <doc xml:space="preserve">A #GBusType.</doc> + <type name="BusType" c:type="GBusType"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.</doc> + <type name="DBusObjectManagerClientFlags" c:type="GDBusObjectManagerClientFlags"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">The owner of the control object (unique or well-known name).</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">The object path of the control object.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="get_proxy_type_func" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="5" destroy="6"> + <doc xml:space="preserve">A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.</doc> + <type name="DBusProxyTypeFunc" c:type="GDBusProxyTypeFunc"/> + </parameter> + <parameter name="get_proxy_type_user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">User data to pass to @get_proxy_type_func.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="get_proxy_type_destroy_notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">Free function for @get_proxy_type_user_data or %NULL.</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_sync" c:identifier="g_dbus_object_manager_client_new_sync" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A + #GDBusObjectManagerClient object or %NULL if @error is set. Free + with g_object_unref().</doc> + <type name="DBusObjectManagerClient" c:type="GDBusObjectManager*"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.</doc> + <type name="DBusObjectManagerClientFlags" c:type="GDBusObjectManagerClientFlags"/> + </parameter> + <parameter name="name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">The object path of the control object.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="get_proxy_type_func" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="5" destroy="6"> + <doc xml:space="preserve">A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.</doc> + <type name="DBusProxyTypeFunc" c:type="GDBusProxyTypeFunc"/> + </parameter> + <parameter name="get_proxy_type_user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">User data to pass to @get_proxy_type_func.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="get_proxy_type_destroy_notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">Free function for @get_proxy_type_user_data or %NULL.</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </constructor> + <function name="new" c:identifier="g_dbus_object_manager_client_new" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.</doc> + <type name="DBusObjectManagerClientFlags" c:type="GDBusObjectManagerClientFlags"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">The owner of the control object (unique or well-known name).</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">The object path of the control object.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="get_proxy_type_func" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="5" destroy="6"> + <doc xml:space="preserve">A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.</doc> + <type name="DBusProxyTypeFunc" c:type="GDBusProxyTypeFunc"/> + </parameter> + <parameter name="get_proxy_type_user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">User data to pass to @get_proxy_type_func.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="get_proxy_type_destroy_notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">Free function for @get_proxy_type_user_data or %NULL.</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="9"> + <doc xml:space="preserve">A #GAsyncReadyCallback to call when the request is satisfied.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The data to pass to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="new_for_bus" c:identifier="g_dbus_object_manager_client_new_for_bus" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="bus_type" transfer-ownership="none"> + <doc xml:space="preserve">A #GBusType.</doc> + <type name="BusType" c:type="GBusType"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.</doc> + <type name="DBusObjectManagerClientFlags" c:type="GDBusObjectManagerClientFlags"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">The owner of the control object (unique or well-known name).</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">The object path of the control object.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="get_proxy_type_func" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="5" destroy="6"> + <doc xml:space="preserve">A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.</doc> + <type name="DBusProxyTypeFunc" c:type="GDBusProxyTypeFunc"/> + </parameter> + <parameter name="get_proxy_type_user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">User data to pass to @get_proxy_type_func.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="get_proxy_type_destroy_notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">Free function for @get_proxy_type_user_data or %NULL.</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="9"> + <doc xml:space="preserve">A #GAsyncReadyCallback to call when the request is satisfied.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The data to pass to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <virtual-method name="interface_proxy_properties_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <type name="DBusObjectManagerClient" c:type="GDBusObjectManagerClient*"/> + </instance-parameter> + <parameter name="object_proxy" transfer-ownership="none"> + <type name="DBusObjectProxy" c:type="GDBusObjectProxy*"/> + </parameter> + <parameter name="interface_proxy" transfer-ownership="none"> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </parameter> + <parameter name="changed_properties" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="invalidated_properties" transfer-ownership="none"> + <type name="utf8" c:type="const gchar* const*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="interface_proxy_signal"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <type name="DBusObjectManagerClient" c:type="GDBusObjectManagerClient*"/> + </instance-parameter> + <parameter name="object_proxy" transfer-ownership="none"> + <type name="DBusObjectProxy" c:type="GDBusObjectProxy*"/> + </parameter> + <parameter name="interface_proxy" transfer-ownership="none"> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </parameter> + <parameter name="sender_name" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="signal_name" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_connection" c:identifier="g_dbus_object_manager_client_get_connection" version="2.30"> + <doc xml:space="preserve">Gets the #GDBusConnection used by @manager.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection object. Do not free, + the object belongs to @manager.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManagerClient</doc> + <type name="DBusObjectManagerClient" c:type="GDBusObjectManagerClient*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_flags" c:identifier="g_dbus_object_manager_client_get_flags" version="2.30"> + <doc xml:space="preserve">Gets the flags that @manager was constructed with.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Zero of more flags from the #GDBusObjectManagerClientFlags +enumeration.</doc> + <type name="DBusObjectManagerClientFlags" c:type="GDBusObjectManagerClientFlags"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManagerClient</doc> + <type name="DBusObjectManagerClient" c:type="GDBusObjectManagerClient*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_name" c:identifier="g_dbus_object_manager_client_get_name" version="2.30"> + <doc xml:space="preserve">Gets the name that @manager is for, or %NULL if not a message bus +connection.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A unique or well-known name. Do not free, the string +belongs to @manager.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManagerClient</doc> + <type name="DBusObjectManagerClient" c:type="GDBusObjectManagerClient*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_name_owner" c:identifier="g_dbus_object_manager_client_get_name_owner" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">The name owner or %NULL if no name owner +exists. Free with g_free().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManagerClient.</doc> + <type name="DBusObjectManagerClient" c:type="GDBusObjectManagerClient*"/> + </instance-parameter> + </parameters> + </method> + <property name="bus-type" version="2.30" readable="0" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="BusType"/> + </property> + <property name="connection" version="2.30" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusConnection to use.</doc> + <type name="DBusConnection"/> + </property> + <property name="flags" version="2.30" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GDBusObjectManagerClientFlags enumeration.</doc> + <type name="DBusObjectManagerClientFlags"/> + </property> + <property name="get-proxy-type-destroy-notify" version="2.30" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data.</doc> + <type name="gpointer" c:type="gpointer"/> + </property> + <property name="get-proxy-type-func" version="2.30" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusProxyTypeFunc to use when determining what #GType to +use for interface proxies or %NULL.</doc> + <type name="gpointer" c:type="gpointer"/> + </property> + <property name="get-proxy-type-user-data" version="2.30" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func.</doc> + <type name="gpointer" c:type="gpointer"/> + </property> + <property name="name" version="2.30" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The well-known name or unique name that the manager is for.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="name-owner" version="2.30" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="object-path" version="2.30" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The object path the manager is for.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <field name="parent_instance" readable="0" private="1"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="DBusObjectManagerClientPrivate" c:type="GDBusObjectManagerClientPrivate*"/> + </field> + <glib:signal name="interface-proxy-properties-changed" when="last" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object_proxy" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusObjectProxy on which an interface has properties that are changing.</doc> + <type name="DBusObjectProxy"/> + </parameter> + <parameter name="interface_proxy" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusProxy that has properties that are changing.</doc> + <type name="DBusProxy"/> + </parameter> + <parameter name="changed_properties" transfer-ownership="none"> + <doc xml:space="preserve">A #GVariant containing the properties that changed (type: `a{sv}`).</doc> + <type name="GLib.Variant"/> + </parameter> + <parameter name="invalidated_properties" transfer-ownership="none"> + <doc xml:space="preserve">A %NULL terminated + array of properties that were invalidated.</doc> + <array> + <type name="utf8"/> + </array> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="interface-proxy-signal" when="last" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object_proxy" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusObjectProxy on which an interface is emitting a D-Bus signal.</doc> + <type name="DBusObjectProxy"/> + </parameter> + <parameter name="interface_proxy" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusProxy that is emitting a D-Bus signal.</doc> + <type name="DBusProxy"/> + </parameter> + <parameter name="sender_name" transfer-ownership="none"> + <doc xml:space="preserve">The sender of the signal or NULL if the connection is not a bus connection.</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="signal_name" transfer-ownership="none"> + <doc xml:space="preserve">The signal name.</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none"> + <doc xml:space="preserve">A #GVariant tuple with parameters for the signal.</doc> + <type name="GLib.Variant"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="DBusObjectManagerClientClass" c:type="GDBusObjectManagerClientClass" glib:is-gtype-struct-for="DBusObjectManagerClient" version="2.30"> + <doc xml:space="preserve">Class structure for #GDBusObjectManagerClient.</doc> + <field name="parent_class"> + <doc xml:space="preserve">The parent class.</doc> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="interface_proxy_signal"> + <callback name="interface_proxy_signal"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="manager" transfer-ownership="none"> + <type name="DBusObjectManagerClient" c:type="GDBusObjectManagerClient*"/> + </parameter> + <parameter name="object_proxy" transfer-ownership="none"> + <type name="DBusObjectProxy" c:type="GDBusObjectProxy*"/> + </parameter> + <parameter name="interface_proxy" transfer-ownership="none"> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </parameter> + <parameter name="sender_name" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="signal_name" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="interface_proxy_properties_changed"> + <callback name="interface_proxy_properties_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="manager" transfer-ownership="none"> + <type name="DBusObjectManagerClient" c:type="GDBusObjectManagerClient*"/> + </parameter> + <parameter name="object_proxy" transfer-ownership="none"> + <type name="DBusObjectProxy" c:type="GDBusObjectProxy*"/> + </parameter> + <parameter name="interface_proxy" transfer-ownership="none"> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </parameter> + <parameter name="changed_properties" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="invalidated_properties" transfer-ownership="none"> + <type name="utf8" c:type="const gchar* const*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="8"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <bitfield name="DBusObjectManagerClientFlags" version="2.30" glib:type-name="GDBusObjectManagerClientFlags" glib:get-type="g_dbus_object_manager_client_flags_get_type" c:type="GDBusObjectManagerClientFlags"> + <doc xml:space="preserve">Flags used when constructing a #GDBusObjectManagerClient.</doc> + <member name="none" value="0" c:identifier="G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="do_not_auto_start" value="1" c:identifier="G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START" glib:nick="do-not-auto-start"> + <doc xml:space="preserve">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.</doc> + </member> + </bitfield> + <record name="DBusObjectManagerClientPrivate" c:type="GDBusObjectManagerClientPrivate" disguised="1"/> + <record name="DBusObjectManagerIface" c:type="GDBusObjectManagerIface" glib:is-gtype-struct-for="DBusObjectManager" version="2.30"> + <doc xml:space="preserve">Base type for D-Bus object managers.</doc> + <field name="parent_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="get_object_path"> + <callback name="get_object_path"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A string owned by @manager. Do not free.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManager.</doc> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_objects"> + <callback name="get_objects"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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().</doc> + <type name="GLib.List" c:type="GList*"> + <type name="DBusObject"/> + </type> + </return-value> + <parameters> + <parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManager.</doc> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_object"> + <callback name="get_object"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusObject or %NULL. Free with + g_object_unref().</doc> + <type name="DBusObject" c:type="GDBusObject*"/> + </return-value> + <parameters> + <parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManager.</doc> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">Object path to look up.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_interface"> + <callback name="get_interface"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusInterface instance or %NULL. Free + with g_object_unref().</doc> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </return-value> + <parameters> + <parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManager.</doc> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">Object path to look up.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">D-Bus interface name to look up.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="object_added"> + <callback name="object_added"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="manager" transfer-ownership="none"> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <type name="DBusObject" c:type="GDBusObject*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="object_removed"> + <callback name="object_removed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="manager" transfer-ownership="none"> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <type name="DBusObject" c:type="GDBusObject*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="interface_added"> + <callback name="interface_added"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="manager" transfer-ownership="none"> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <type name="DBusObject" c:type="GDBusObject*"/> + </parameter> + <parameter name="interface_" transfer-ownership="none"> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="interface_removed"> + <callback name="interface_removed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="manager" transfer-ownership="none"> + <type name="DBusObjectManager" c:type="GDBusObjectManager*"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <type name="DBusObject" c:type="GDBusObject*"/> + </parameter> + <parameter name="interface_" transfer-ownership="none"> + <type name="DBusInterface" c:type="GDBusInterface*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="DBusObjectManagerServer" c:symbol-prefix="dbus_object_manager_server" c:type="GDBusObjectManagerServer" version="2.30" parent="GObject.Object" glib:type-name="GDBusObjectManagerServer" glib:get-type="g_dbus_object_manager_server_get_type" glib:type-struct="DBusObjectManagerServerClass"> + <doc xml:space="preserve">#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.</doc> + <implements name="DBusObjectManager"/> + <constructor name="new" c:identifier="g_dbus_object_manager_server_new" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusObjectManagerServer object. Free with g_object_unref().</doc> + <type name="DBusObjectManagerServer" c:type="GDBusObjectManagerServer*"/> + </return-value> + <parameters> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">The object path to export the manager object at.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <method name="export" c:identifier="g_dbus_object_manager_server_export" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManagerServer.</doc> + <type name="DBusObjectManagerServer" c:type="GDBusObjectManagerServer*"/> + </instance-parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectSkeleton.</doc> + <type name="DBusObjectSkeleton" c:type="GDBusObjectSkeleton*"/> + </parameter> + </parameters> + </method> + <method name="export_uniquely" c:identifier="g_dbus_object_manager_server_export_uniquely" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManagerServer.</doc> + <type name="DBusObjectManagerServer" c:type="GDBusObjectManagerServer*"/> + </instance-parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">An object.</doc> + <type name="DBusObjectSkeleton" c:type="GDBusObjectSkeleton*"/> + </parameter> + </parameters> + </method> + <method name="get_connection" c:identifier="g_dbus_object_manager_server_get_connection" version="2.30"> + <doc xml:space="preserve">Gets the #GDBusConnection used by @manager.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusConnection object or %NULL if + @manager isn't exported on a connection. The returned object should + be freed with g_object_unref().</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManagerServer</doc> + <type name="DBusObjectManagerServer" c:type="GDBusObjectManagerServer*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_exported" c:identifier="g_dbus_object_manager_server_is_exported" version="2.34"> + <doc xml:space="preserve">Returns whether @object is currently exported on @manager.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @object is exported</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManagerServer.</doc> + <type name="DBusObjectManagerServer" c:type="GDBusObjectManagerServer*"/> + </instance-parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">An object.</doc> + <type name="DBusObjectSkeleton" c:type="GDBusObjectSkeleton*"/> + </parameter> + </parameters> + </method> + <method name="set_connection" c:identifier="g_dbus_object_manager_server_set_connection"> + <doc xml:space="preserve">Exports all objects managed by @manager on @connection. If +@connection is %NULL, stops exporting objects.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManagerServer.</doc> + <type name="DBusObjectManagerServer" c:type="GDBusObjectManagerServer*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GDBusConnection or %NULL.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + </parameters> + </method> + <method name="unexport" c:identifier="g_dbus_object_manager_server_unexport" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if object at @object_path was removed, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManagerServer.</doc> + <type name="DBusObjectManagerServer" c:type="GDBusObjectManagerServer*"/> + </instance-parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">An object path.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <property name="connection" version="2.30" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusConnection to export objects on.</doc> + <type name="DBusConnection"/> + </property> + <property name="object-path" version="2.30" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The object path to register the manager object at.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <field name="parent_instance" readable="0" private="1"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="DBusObjectManagerServerPrivate" c:type="GDBusObjectManagerServerPrivate*"/> + </field> + </class> + <record name="DBusObjectManagerServerClass" c:type="GDBusObjectManagerServerClass" glib:is-gtype-struct-for="DBusObjectManagerServer" version="2.30"> + <doc xml:space="preserve">Class structure for #GDBusObjectManagerServer.</doc> + <field name="parent_class"> + <doc xml:space="preserve">The parent class.</doc> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="8"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <record name="DBusObjectManagerServerPrivate" c:type="GDBusObjectManagerServerPrivate" disguised="1"/> + <class name="DBusObjectProxy" c:symbol-prefix="dbus_object_proxy" c:type="GDBusObjectProxy" version="2.30" parent="GObject.Object" glib:type-name="GDBusObjectProxy" glib:get-type="g_dbus_object_proxy_get_type" glib:type-struct="DBusObjectProxyClass"> + <doc xml:space="preserve">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.</doc> + <implements name="DBusObject"/> + <constructor name="new" c:identifier="g_dbus_object_proxy_new" version="2.30"> + <doc xml:space="preserve">Creates a new #GDBusObjectProxy for the given connection and +object path.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GDBusObjectProxy</doc> + <type name="DBusObjectProxy" c:type="GDBusObjectProxy*"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">the object path</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <method name="get_connection" c:identifier="g_dbus_object_proxy_get_connection" version="2.30"> + <doc xml:space="preserve">Gets the connection that @proxy is for.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection. Do not free, the + object is owned by @proxy.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusObjectProxy</doc> + <type name="DBusObjectProxy" c:type="GDBusObjectProxy*"/> + </instance-parameter> + </parameters> + </method> + <property name="g-connection" version="2.30" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The connection of the proxy.</doc> + <type name="DBusConnection"/> + </property> + <property name="g-object-path" version="2.30" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The object path of the proxy.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <field name="parent_instance" readable="0" private="1"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="DBusObjectProxyPrivate" c:type="GDBusObjectProxyPrivate*"/> + </field> + </class> + <record name="DBusObjectProxyClass" c:type="GDBusObjectProxyClass" glib:is-gtype-struct-for="DBusObjectProxy" version="2.30"> + <doc xml:space="preserve">Class structure for #GDBusObjectProxy.</doc> + <field name="parent_class"> + <doc xml:space="preserve">The parent class.</doc> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="8"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <record name="DBusObjectProxyPrivate" c:type="GDBusObjectProxyPrivate" disguised="1"/> + <class name="DBusObjectSkeleton" c:symbol-prefix="dbus_object_skeleton" c:type="GDBusObjectSkeleton" version="2.30" parent="GObject.Object" glib:type-name="GDBusObjectSkeleton" glib:get-type="g_dbus_object_skeleton_get_type" glib:type-struct="DBusObjectSkeletonClass"> + <doc xml:space="preserve">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.</doc> + <implements name="DBusObject"/> + <constructor name="new" c:identifier="g_dbus_object_skeleton_new" version="2.30"> + <doc xml:space="preserve">Creates a new #GDBusObjectSkeleton.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusObjectSkeleton. Free with g_object_unref().</doc> + <type name="DBusObjectSkeleton" c:type="GDBusObjectSkeleton*"/> + </return-value> + <parameters> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">An object path.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <virtual-method name="authorize_method"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <type name="DBusObjectSkeleton" c:type="GDBusObjectSkeleton*"/> + </instance-parameter> + <parameter name="interface_" transfer-ownership="none"> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </parameter> + <parameter name="invocation" transfer-ownership="none"> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </parameter> + </parameters> + </virtual-method> + <method name="add_interface" c:identifier="g_dbus_object_skeleton_add_interface" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectSkeleton.</doc> + <type name="DBusObjectSkeleton" c:type="GDBusObjectSkeleton*"/> + </instance-parameter> + <parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </parameter> + </parameters> + </method> + <method name="flush" c:identifier="g_dbus_object_skeleton_flush" version="2.30"> + <doc xml:space="preserve">This method simply calls g_dbus_interface_skeleton_flush() on all +interfaces belonging to @object. See that method for when flushing +is useful.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectSkeleton.</doc> + <type name="DBusObjectSkeleton" c:type="GDBusObjectSkeleton*"/> + </instance-parameter> + </parameters> + </method> + <method name="remove_interface" c:identifier="g_dbus_object_skeleton_remove_interface" version="2.30"> + <doc xml:space="preserve">Removes @interface_ from @object.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectSkeleton.</doc> + <type name="DBusObjectSkeleton" c:type="GDBusObjectSkeleton*"/> + </instance-parameter> + <parameter name="interface_" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceSkeleton.</doc> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </parameter> + </parameters> + </method> + <method name="remove_interface_by_name" c:identifier="g_dbus_object_skeleton_remove_interface_by_name" version="2.30"> + <doc xml:space="preserve">Removes the #GDBusInterface with @interface_name from @object. + +If no D-Bus interface of the given interface exists, this function +does nothing.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectSkeleton.</doc> + <type name="DBusObjectSkeleton" c:type="GDBusObjectSkeleton*"/> + </instance-parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus interface name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_object_path" c:identifier="g_dbus_object_skeleton_set_object_path" version="2.30"> + <doc xml:space="preserve">Sets the object path for @object.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectSkeleton.</doc> + <type name="DBusObjectSkeleton" c:type="GDBusObjectSkeleton*"/> + </instance-parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">A valid D-Bus object path.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <property name="g-object-path" version="2.30" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">The object path where the object is exported.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <field name="parent_instance" readable="0" private="1"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="DBusObjectSkeletonPrivate" c:type="GDBusObjectSkeletonPrivate*"/> + </field> + <glib:signal name="authorize-method" when="last" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the call is authorized, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="interface" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusInterfaceSkeleton that @invocation is for.</doc> + <type name="DBusInterfaceSkeleton"/> + </parameter> + <parameter name="invocation" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusMethodInvocation.</doc> + <type name="DBusMethodInvocation"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="DBusObjectSkeletonClass" c:type="GDBusObjectSkeletonClass" glib:is-gtype-struct-for="DBusObjectSkeleton" version="2.30"> + <doc xml:space="preserve">Class structure for #GDBusObjectSkeleton.</doc> + <field name="parent_class"> + <doc xml:space="preserve">The parent class.</doc> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="authorize_method"> + <callback name="authorize_method"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <type name="DBusObjectSkeleton" c:type="GDBusObjectSkeleton*"/> + </parameter> + <parameter name="interface_" transfer-ownership="none"> + <type name="DBusInterfaceSkeleton" c:type="GDBusInterfaceSkeleton*"/> + </parameter> + <parameter name="invocation" transfer-ownership="none"> + <type name="DBusMethodInvocation" c:type="GDBusMethodInvocation*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="8"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <record name="DBusObjectSkeletonPrivate" c:type="GDBusObjectSkeletonPrivate" disguised="1"/> + <record name="DBusPropertyInfo" c:type="GDBusPropertyInfo" version="2.26" glib:type-name="GDBusPropertyInfo" glib:get-type="g_dbus_property_info_get_type" c:symbol-prefix="dbus_property_info"> + <doc xml:space="preserve">Information about a D-Bus property on a D-Bus interface.</doc> + <field name="ref_count" writable="1"> + <doc xml:space="preserve">The reference count or -1 if statically allocated.</doc> + <type name="gint" c:type="volatile gint"/> + </field> + <field name="name" writable="1"> + <doc xml:space="preserve">The name of the D-Bus property, e.g. "SupportedFilesystems".</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="signature" writable="1"> + <doc xml:space="preserve">The D-Bus signature of the property (a single complete type).</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="flags" writable="1"> + <doc xml:space="preserve">Access control flags for the property.</doc> + <type name="DBusPropertyInfoFlags" c:type="GDBusPropertyInfoFlags"/> + </field> + <field name="annotations" writable="1"> + <doc xml:space="preserve">A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.</doc> + <array c:type="GDBusAnnotationInfo**"> + <type name="DBusAnnotationInfo" c:type="GDBusAnnotationInfo*"/> + </array> + </field> + <method name="ref" c:identifier="g_dbus_property_info_ref" version="2.26"> + <doc xml:space="preserve">If @info is statically allocated does nothing. Otherwise increases +the reference count.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">The same @info.</doc> + <type name="DBusPropertyInfo" c:type="GDBusPropertyInfo*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusPropertyInfo</doc> + <type name="DBusPropertyInfo" c:type="GDBusPropertyInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_dbus_property_info_unref" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusPropertyInfo.</doc> + <type name="DBusPropertyInfo" c:type="GDBusPropertyInfo*"/> + </instance-parameter> + </parameters> + </method> + </record> + <bitfield name="DBusPropertyInfoFlags" version="2.26" glib:type-name="GDBusPropertyInfoFlags" glib:get-type="g_dbus_property_info_flags_get_type" c:type="GDBusPropertyInfoFlags"> + <doc xml:space="preserve">Flags describing the access control of a D-Bus property.</doc> + <member name="none" value="0" c:identifier="G_DBUS_PROPERTY_INFO_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="readable" value="1" c:identifier="G_DBUS_PROPERTY_INFO_FLAGS_READABLE" glib:nick="readable"> + <doc xml:space="preserve">Property is readable.</doc> + </member> + <member name="writable" value="2" c:identifier="G_DBUS_PROPERTY_INFO_FLAGS_WRITABLE" glib:nick="writable"> + <doc xml:space="preserve">Property is writable.</doc> + </member> + </bitfield> + <class name="DBusProxy" c:symbol-prefix="dbus_proxy" c:type="GDBusProxy" version="2.26" parent="GObject.Object" glib:type-name="GDBusProxy" glib:get-type="g_dbus_proxy_get_type" glib:type-struct="DBusProxyClass"> + <doc xml:space="preserve">#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)</doc> + <implements name="AsyncInitable"/> + <implements name="DBusInterface"/> + <implements name="Initable"/> + <constructor name="new_finish" c:identifier="g_dbus_proxy_new_finish" version="2.26" throws="1"> + <doc xml:space="preserve">Finishes creating a #GDBusProxy.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusProxy or %NULL if @error is set. + Free with g_object_unref().</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </return-value> + <parameters> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new().</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_for_bus_finish" c:identifier="g_dbus_proxy_new_for_bus_finish" version="2.26" throws="1"> + <doc xml:space="preserve">Finishes creating a #GDBusProxy.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusProxy or %NULL if @error is set. + Free with g_object_unref().</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </return-value> + <parameters> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus().</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_for_bus_sync" c:identifier="g_dbus_proxy_new_for_bus_sync" version="2.26" throws="1"> + <doc xml:space="preserve">Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. + +#GDBusProxy is used in this [example][gdbus-wellknown-proxy].</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusProxy or %NULL if error is set. + Free with g_object_unref().</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </return-value> + <parameters> + <parameter name="bus_type" transfer-ownership="none"> + <doc xml:space="preserve">A #GBusType.</doc> + <type name="BusType" c:type="GBusType"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags used when constructing the proxy.</doc> + <type name="DBusProxyFlags" c:type="GDBusProxyFlags"/> + </parameter> + <parameter name="info" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GDBusInterfaceInfo specifying the minimal interface + that @proxy conforms to or %NULL.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">A bus name (well-known or unique).</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">An object path.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus interface name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_sync" c:identifier="g_dbus_proxy_new_sync" version="2.26" throws="1"> + <doc xml:space="preserve">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].</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusProxy or %NULL if error is set. + Free with g_object_unref().</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags used when constructing the proxy.</doc> + <type name="DBusProxyFlags" c:type="GDBusProxyFlags"/> + </parameter> + <parameter name="info" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </parameter> + <parameter name="name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">An object path.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus interface name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </constructor> + <function name="new" c:identifier="g_dbus_proxy_new" version="2.26"> + <doc xml:space="preserve">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].</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags used when constructing the proxy.</doc> + <type name="DBusProxyFlags" c:type="GDBusProxyFlags"/> + </parameter> + <parameter name="info" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </parameter> + <parameter name="name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">An object path.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus interface name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="8"> + <doc xml:space="preserve">Callback function to invoke when the proxy is ready.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">User data to pass to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="new_for_bus" c:identifier="g_dbus_proxy_new_for_bus" version="2.26"> + <doc xml:space="preserve">Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection. + +#GDBusProxy is used in this [example][gdbus-wellknown-proxy].</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="bus_type" transfer-ownership="none"> + <doc xml:space="preserve">A #GBusType.</doc> + <type name="BusType" c:type="GBusType"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags used when constructing the proxy.</doc> + <type name="DBusProxyFlags" c:type="GDBusProxyFlags"/> + </parameter> + <parameter name="info" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">A bus name (well-known or unique).</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">An object path.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus interface name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="8"> + <doc xml:space="preserve">Callback function to invoke when the proxy is ready.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">User data to pass to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <virtual-method name="g_properties_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + <parameter name="changed_properties" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="invalidated_properties" transfer-ownership="none"> + <type name="utf8" c:type="const gchar* const*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="g_signal"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + <parameter name="sender_name" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="signal_name" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <method name="call" c:identifier="g_dbus_proxy_call" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy.</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + <parameter name="method_name" transfer-ownership="none"> + <doc xml:space="preserve">Name of method to invoke.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GDBusCallFlags enumeration.</doc> + <type name="DBusCallFlags" c:type="GDBusCallFlags"/> + </parameter> + <parameter name="timeout_msec" transfer-ownership="none"> + <doc xml:space="preserve">The timeout in milliseconds (with %G_MAXINT meaning + "infinite") or -1 to use the proxy default timeout.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't +care about the result of the method invocation.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The data to pass to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="call_finish" c:identifier="g_dbus_proxy_call_finish" version="2.26" throws="1"> + <doc xml:space="preserve">Finishes an operation started with g_dbus_proxy_call().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">%NULL if @error is set. Otherwise a #GVariant tuple with +return values. Free with g_variant_unref().</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy.</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call().</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="call_sync" c:identifier="g_dbus_proxy_call_sync" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">%NULL if @error is set. Otherwise a #GVariant tuple with +return values. Free with g_variant_unref().</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy.</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + <parameter name="method_name" transfer-ownership="none"> + <doc xml:space="preserve">Name of method to invoke.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GVariant tuple with parameters for the signal + or %NULL if not passing parameters.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GDBusCallFlags enumeration.</doc> + <type name="DBusCallFlags" c:type="GDBusCallFlags"/> + </parameter> + <parameter name="timeout_msec" transfer-ownership="none"> + <doc xml:space="preserve">The timeout in milliseconds (with %G_MAXINT meaning + "infinite") or -1 to use the proxy default timeout.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="call_with_unix_fd_list" c:identifier="g_dbus_proxy_call_with_unix_fd_list" version="2.30"> + <doc xml:space="preserve">Like g_dbus_proxy_call() but also takes a #GUnixFDList object. + +This method is only available on UNIX.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy.</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + <parameter name="method_name" transfer-ownership="none"> + <doc xml:space="preserve">Name of method to invoke.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GDBusCallFlags enumeration.</doc> + <type name="DBusCallFlags" c:type="GDBusCallFlags"/> + </parameter> + <parameter name="timeout_msec" transfer-ownership="none"> + <doc xml:space="preserve">The timeout in milliseconds (with %G_MAXINT meaning + "infinite") or -1 to use the proxy default timeout.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="fd_list" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GUnixFDList or %NULL.</doc> + <type name="UnixFDList" c:type="GUnixFDList*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="7"> + <doc xml:space="preserve">A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't +care about the result of the method invocation.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The data to pass to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="call_with_unix_fd_list_finish" c:identifier="g_dbus_proxy_call_with_unix_fd_list_finish" version="2.30" throws="1"> + <doc xml:space="preserve">Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">%NULL if @error is set. Otherwise a #GVariant tuple with +return values. Free with g_variant_unref().</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy.</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + <parameter name="out_fd_list" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">Return location for a #GUnixFDList or %NULL.</doc> + <type name="UnixFDList" c:type="GUnixFDList**"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list().</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="call_with_unix_fd_list_sync" c:identifier="g_dbus_proxy_call_with_unix_fd_list_sync" version="2.30" throws="1"> + <doc xml:space="preserve">Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects. + +This method is only available on UNIX.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">%NULL if @error is set. Otherwise a #GVariant tuple with +return values. Free with g_variant_unref().</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy.</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + <parameter name="method_name" transfer-ownership="none"> + <doc xml:space="preserve">Name of method to invoke.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GVariant tuple with parameters for the signal + or %NULL if not passing parameters.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GDBusCallFlags enumeration.</doc> + <type name="DBusCallFlags" c:type="GDBusCallFlags"/> + </parameter> + <parameter name="timeout_msec" transfer-ownership="none"> + <doc xml:space="preserve">The timeout in milliseconds (with %G_MAXINT meaning + "infinite") or -1 to use the proxy default timeout.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="fd_list" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GUnixFDList or %NULL.</doc> + <type name="UnixFDList" c:type="GUnixFDList*"/> + </parameter> + <parameter name="out_fd_list" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">Return location for a #GUnixFDList or %NULL.</doc> + <type name="UnixFDList" c:type="GUnixFDList**"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="get_cached_property" c:identifier="g_dbus_proxy_get_cached_property" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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().</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy.</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + <parameter name="property_name" transfer-ownership="none"> + <doc xml:space="preserve">Property name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_cached_property_names" c:identifier="g_dbus_proxy_get_cached_property_names" version="2.26"> + <doc xml:space="preserve">Gets the names of all cached properties on @proxy.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">A + %NULL-terminated array of strings or %NULL if + @proxy has no cached properties. Free the returned array with + g_strfreev().</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy.</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_connection" c:identifier="g_dbus_proxy_get_connection" version="2.26"> + <doc xml:space="preserve">Gets the connection @proxy is for.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection owned by @proxy. Do not free.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy.</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_default_timeout" c:identifier="g_dbus_proxy_get_default_timeout" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Timeout to use for @proxy.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy.</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_flags" c:identifier="g_dbus_proxy_get_flags" version="2.26"> + <doc xml:space="preserve">Gets the flags that @proxy was constructed with.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GDBusProxyFlags enumeration.</doc> + <type name="DBusProxyFlags" c:type="GDBusProxyFlags"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy.</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_interface_info" c:identifier="g_dbus_proxy_get_interface_info" version="2.26"> + <doc xml:space="preserve">Returns the #GDBusInterfaceInfo, if any, specifying the interface +that @proxy conforms to. See the #GDBusProxy:g-interface-info +property for more details.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">A #GDBusInterfaceInfo or %NULL. + Do not unref the returned object, it is owned by @proxy.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_interface_name" c:identifier="g_dbus_proxy_get_interface_name" version="2.26"> + <doc xml:space="preserve">Gets the D-Bus interface name @proxy is for.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A string owned by @proxy. Do not free.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy.</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_name" c:identifier="g_dbus_proxy_get_name" version="2.26"> + <doc xml:space="preserve">Gets the name that @proxy was constructed for.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A string owned by @proxy. Do not free.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy.</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_name_owner" c:identifier="g_dbus_proxy_get_name_owner" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">The name owner or %NULL if no name + owner exists. Free with g_free().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy.</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_object_path" c:identifier="g_dbus_proxy_get_object_path" version="2.26"> + <doc xml:space="preserve">Gets the object path @proxy is for.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A string owned by @proxy. Do not free.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy.</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_cached_property" c:identifier="g_dbus_proxy_set_cached_property" version="2.26"> + <doc xml:space="preserve">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)`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + <parameter name="property_name" transfer-ownership="none"> + <doc xml:space="preserve">Property name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Value for the property or %NULL to remove it from the cache.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="set_default_timeout" c:identifier="g_dbus_proxy_set_default_timeout" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy.</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + <parameter name="timeout_msec" transfer-ownership="none"> + <doc xml:space="preserve">Timeout in milliseconds.</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="set_interface_info" c:identifier="g_dbus_proxy_set_interface_info" version="2.26"> + <doc xml:space="preserve">Ensure that interactions with @proxy conform to the given +interface. See the #GDBusProxy:g-interface-info property for more +details.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusProxy</doc> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </instance-parameter> + <parameter name="info" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Minimum interface this proxy conforms to + or %NULL to unset.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo*"/> + </parameter> + </parameters> + </method> + <property name="g-bus-type" version="2.26" readable="0" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="BusType"/> + </property> + <property name="g-connection" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The #GDBusConnection the proxy is for.</doc> + <type name="DBusConnection"/> + </property> + <property name="g-default-timeout" version="2.26" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </property> + <property name="g-flags" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GDBusProxyFlags enumeration.</doc> + <type name="DBusProxyFlags"/> + </property> + <property name="g-interface-info" version="2.26" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="DBusInterfaceInfo"/> + </property> + <property name="g-interface-name" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The D-Bus interface name the proxy is for.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="g-name" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The well-known or unique name that the proxy is for.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="g-name-owner" version="2.26" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="g-object-path" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The object path the proxy is for.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <field name="parent_instance" readable="0" private="1"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="DBusProxyPrivate" c:type="GDBusProxyPrivate*"/> + </field> + <glib:signal name="g-properties-changed" when="last" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="changed_properties" transfer-ownership="none"> + <doc xml:space="preserve">A #GVariant containing the properties that changed (type: `a{sv}`)</doc> + <type name="GLib.Variant"/> + </parameter> + <parameter name="invalidated_properties" transfer-ownership="none"> + <doc xml:space="preserve">A %NULL terminated array of properties that was invalidated</doc> + <array> + <type name="utf8"/> + </array> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="g-signal" when="last" version="2.26"> + <doc xml:space="preserve">Emitted when a signal from the remote object and interface that @proxy is for, has been received.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="sender_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The sender of the signal or %NULL if the connection is not a bus connection.</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="signal_name" transfer-ownership="none"> + <doc xml:space="preserve">The name of the signal.</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none"> + <doc xml:space="preserve">A #GVariant tuple with parameters for the signal.</doc> + <type name="GLib.Variant"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="DBusProxyClass" c:type="GDBusProxyClass" glib:is-gtype-struct-for="DBusProxy" version="2.26"> + <doc xml:space="preserve">Class structure for #GDBusProxy.</doc> + <field name="parent_class" readable="0" private="1"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="g_properties_changed"> + <callback name="g_properties_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="proxy" transfer-ownership="none"> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </parameter> + <parameter name="changed_properties" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="invalidated_properties" transfer-ownership="none"> + <type name="utf8" c:type="const gchar* const*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="g_signal"> + <callback name="g_signal"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="proxy" transfer-ownership="none"> + <type name="DBusProxy" c:type="GDBusProxy*"/> + </parameter> + <parameter name="sender_name" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="signal_name" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="32"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <bitfield name="DBusProxyFlags" version="2.26" glib:type-name="GDBusProxyFlags" glib:get-type="g_dbus_proxy_flags_get_type" c:type="GDBusProxyFlags"> + <doc xml:space="preserve">Flags used when constructing an instance of a #GDBusProxy derived class.</doc> + <member name="none" value="0" c:identifier="G_DBUS_PROXY_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="do_not_load_properties" value="1" c:identifier="G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES" glib:nick="do-not-load-properties"> + <doc xml:space="preserve">Don't load properties.</doc> + </member> + <member name="do_not_connect_signals" value="2" c:identifier="G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS" glib:nick="do-not-connect-signals"> + <doc xml:space="preserve">Don't connect to signals on the remote object.</doc> + </member> + <member name="do_not_auto_start" value="4" c:identifier="G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START" glib:nick="do-not-auto-start"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="get_invalidated_properties" value="8" c:identifier="G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES" glib:nick="get-invalidated-properties"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="do_not_auto_start_at_construction" value="16" c:identifier="G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION" glib:nick="do-not-auto-start-at-construction"> + <doc xml:space="preserve">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.</doc> + </member> + </bitfield> + <record name="DBusProxyPrivate" c:type="GDBusProxyPrivate" disguised="1"/> + <callback name="DBusProxyTypeFunc" c:type="GDBusProxyTypeFunc" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A #GType to use for the remote object. The returned type + must be a #GDBusProxy or #GDBusObjectProxy -derived + type.</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <parameter name="manager" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusObjectManagerClient.</doc> + <type name="DBusObjectManagerClient" c:type="GDBusObjectManagerClient*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">The object path of the remote object.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The interface name of the remote object or %NULL if a #GDBusObjectProxy #GType is requested.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">User data.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <bitfield name="DBusSendMessageFlags" version="2.26" glib:type-name="GDBusSendMessageFlags" glib:get-type="g_dbus_send_message_flags_get_type" c:type="GDBusSendMessageFlags"> + <doc xml:space="preserve">Flags used when sending #GDBusMessages on a #GDBusConnection.</doc> + <member name="none" value="0" c:identifier="G_DBUS_SEND_MESSAGE_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="preserve_serial" value="1" c:identifier="G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL" glib:nick="preserve-serial"> + <doc xml:space="preserve">Do not automatically +assign a serial number from the #GDBusConnection object when +sending a message.</doc> + </member> + </bitfield> + <class name="DBusServer" c:symbol-prefix="dbus_server" c:type="GDBusServer" version="2.26" parent="GObject.Object" glib:type-name="GDBusServer" glib:get-type="g_dbus_server_get_type"> + <doc xml:space="preserve">#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 GDBus 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. Since GLib 2.68 this can +be achieved more simply by passing the +%G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag to the server.</doc> + <implements name="Initable"/> + <constructor name="new_sync" c:identifier="g_dbus_server_new_sync" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GDBusServer or %NULL if @error is set. Free with +g_object_unref().</doc> + <type name="DBusServer" c:type="GDBusServer*"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus address.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GDBusServerFlags enumeration.</doc> + <type name="DBusServerFlags" c:type="GDBusServerFlags"/> + </parameter> + <parameter name="guid" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus GUID.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="observer" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GDBusAuthObserver or %NULL.</doc> + <type name="DBusAuthObserver" c:type="GDBusAuthObserver*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </constructor> + <method name="get_client_address" c:identifier="g_dbus_server_get_client_address" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus address string. Do not free, the string is owned +by @server.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="server" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusServer.</doc> + <type name="DBusServer" c:type="GDBusServer*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_flags" c:identifier="g_dbus_server_get_flags" version="2.26"> + <doc xml:space="preserve">Gets the flags for @server.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A set of flags from the #GDBusServerFlags enumeration.</doc> + <type name="DBusServerFlags" c:type="GDBusServerFlags"/> + </return-value> + <parameters> + <instance-parameter name="server" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusServer.</doc> + <type name="DBusServer" c:type="GDBusServer*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_guid" c:identifier="g_dbus_server_get_guid" version="2.26"> + <doc xml:space="preserve">Gets the GUID for @server.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus GUID. Do not free this string, it is owned by @server.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="server" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusServer.</doc> + <type name="DBusServer" c:type="GDBusServer*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_active" c:identifier="g_dbus_server_is_active" version="2.26"> + <doc xml:space="preserve">Gets whether @server is active.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if server is active, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="server" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusServer.</doc> + <type name="DBusServer" c:type="GDBusServer*"/> + </instance-parameter> + </parameters> + </method> + <method name="start" c:identifier="g_dbus_server_start" version="2.26"> + <doc xml:space="preserve">Starts @server.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="server" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusServer.</doc> + <type name="DBusServer" c:type="GDBusServer*"/> + </instance-parameter> + </parameters> + </method> + <method name="stop" c:identifier="g_dbus_server_stop" version="2.26"> + <doc xml:space="preserve">Stops @server.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="server" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusServer.</doc> + <type name="DBusServer" c:type="GDBusServer*"/> + </instance-parameter> + </parameters> + </method> + <property name="active" version="2.26" transfer-ownership="none"> + <doc xml:space="preserve">Whether the server is currently active.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="address" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The D-Bus address to listen on.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="authentication-observer" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusAuthObserver object to assist in the authentication process or %NULL.</doc> + <type name="DBusAuthObserver"/> + </property> + <property name="client-address" version="2.26" transfer-ownership="none"> + <doc xml:space="preserve">The D-Bus address that clients can use.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="flags" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GDBusServerFlags enumeration.</doc> + <type name="DBusServerFlags"/> + </property> + <property name="guid" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The guid of the server.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <glib:signal name="new-connection" when="last" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to claim @connection, %FALSE to let other handlers +run.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection for the new connection.</doc> + <type name="DBusConnection"/> + </parameter> + </parameters> + </glib:signal> + </class> + <bitfield name="DBusServerFlags" version="2.26" glib:type-name="GDBusServerFlags" glib:get-type="g_dbus_server_flags_get_type" c:type="GDBusServerFlags"> + <doc xml:space="preserve">Flags used when creating a #GDBusServer.</doc> + <member name="none" value="0" c:identifier="G_DBUS_SERVER_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="run_in_thread" value="1" c:identifier="G_DBUS_SERVER_FLAGS_RUN_IN_THREAD" glib:nick="run-in-thread"> + <doc xml:space="preserve">All #GDBusServer::new-connection +signals will run in separated dedicated threads (see signal for +details).</doc> + </member> + <member name="authentication_allow_anonymous" value="2" c:identifier="G_DBUS_SERVER_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS" glib:nick="authentication-allow-anonymous"> + <doc xml:space="preserve">Allow the anonymous +authentication method.</doc> + </member> + </bitfield> + <callback name="DBusSignalCallback" c:type="GDBusSignalCallback" version="2.26"> + <doc xml:space="preserve">Signature for callback function used in g_dbus_connection_signal_subscribe().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="sender_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The unique bus name of the sender of the signal, + or %NULL on a peer-to-peer D-Bus connection.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">The object path that the signal was emitted on.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">The name of the interface.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="signal_name" transfer-ownership="none"> + <doc xml:space="preserve">The name of the signal.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameters" transfer-ownership="none"> + <doc xml:space="preserve">A #GVariant tuple with parameters for the signal.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">User data passed when subscribing to the signal.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <bitfield name="DBusSignalFlags" version="2.26" glib:type-name="GDBusSignalFlags" glib:get-type="g_dbus_signal_flags_get_type" c:type="GDBusSignalFlags"> + <doc xml:space="preserve">Flags used when subscribing to signals via g_dbus_connection_signal_subscribe().</doc> + <member name="none" value="0" c:identifier="G_DBUS_SIGNAL_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="no_match_rule" value="1" c:identifier="G_DBUS_SIGNAL_FLAGS_NO_MATCH_RULE" glib:nick="no-match-rule"> + <doc xml:space="preserve">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).</doc> + </member> + <member name="match_arg0_namespace" value="2" c:identifier="G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE" glib:nick="match-arg0-namespace"> + <doc xml:space="preserve">Match first arguments that +contain a bus or interface name with the given namespace.</doc> + </member> + <member name="match_arg0_path" value="4" c:identifier="G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH" glib:nick="match-arg0-path"> + <doc xml:space="preserve">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.</doc> + </member> + </bitfield> + <record name="DBusSignalInfo" c:type="GDBusSignalInfo" version="2.26" glib:type-name="GDBusSignalInfo" glib:get-type="g_dbus_signal_info_get_type" c:symbol-prefix="dbus_signal_info"> + <doc xml:space="preserve">Information about a signal on a D-Bus interface.</doc> + <field name="ref_count" writable="1"> + <doc xml:space="preserve">The reference count or -1 if statically allocated.</doc> + <type name="gint" c:type="volatile gint"/> + </field> + <field name="name" writable="1"> + <doc xml:space="preserve">The name of the D-Bus signal, e.g. "NameOwnerChanged".</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="args" writable="1"> + <doc xml:space="preserve">A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no arguments.</doc> + <array c:type="GDBusArgInfo**"> + <type name="DBusArgInfo" c:type="GDBusArgInfo*"/> + </array> + </field> + <field name="annotations" writable="1"> + <doc xml:space="preserve">A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.</doc> + <array c:type="GDBusAnnotationInfo**"> + <type name="DBusAnnotationInfo" c:type="GDBusAnnotationInfo*"/> + </array> + </field> + <method name="ref" c:identifier="g_dbus_signal_info_ref" version="2.26"> + <doc xml:space="preserve">If @info is statically allocated does nothing. Otherwise increases +the reference count.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">The same @info.</doc> + <type name="DBusSignalInfo" c:type="GDBusSignalInfo*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusSignalInfo</doc> + <type name="DBusSignalInfo" c:type="GDBusSignalInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_dbus_signal_info_unref" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusSignalInfo.</doc> + <type name="DBusSignalInfo" c:type="GDBusSignalInfo*"/> + </instance-parameter> + </parameters> + </method> + </record> + <callback name="DBusSubtreeDispatchFunc" c:type="GDBusSubtreeDispatchFunc" version="2.26"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.</doc> + <type name="DBusInterfaceVTable" c:type="const GDBusInterfaceVTable*"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="sender" transfer-ownership="none"> + <doc xml:space="preserve">The unique bus name of the remote caller.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">The object path that was registered with g_dbus_connection_register_subtree().</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interface_name" transfer-ownership="none"> + <doc xml:space="preserve">The D-Bus interface name that the method call or property access is for.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="out_user_data" transfer-ownership="none"> + <doc xml:space="preserve">Return location for user data to pass to functions in the returned #GDBusInterfaceVTable.</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">The @user_data #gpointer passed to g_dbus_connection_register_subtree().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="DBusSubtreeEnumerateFunc" c:type="GDBusSubtreeEnumerateFunc" version="2.26" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value> + <doc xml:space="preserve">A newly allocated array of strings for node names that are children of @object_path.</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="sender" transfer-ownership="none"> + <doc xml:space="preserve">The unique bus name of the remote caller.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">The object path that was registered with g_dbus_connection_register_subtree().</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">The @user_data #gpointer passed to g_dbus_connection_register_subtree().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <bitfield name="DBusSubtreeFlags" version="2.26" glib:type-name="GDBusSubtreeFlags" glib:get-type="g_dbus_subtree_flags_get_type" c:type="GDBusSubtreeFlags"> + <doc xml:space="preserve">Flags passed to g_dbus_connection_register_subtree().</doc> + <member name="none" value="0" c:identifier="G_DBUS_SUBTREE_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="dispatch_to_unenumerated_nodes" value="1" c:identifier="G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES" glib:nick="dispatch-to-unenumerated-nodes"> + <doc xml:space="preserve">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.</doc> + </member> + </bitfield> + <callback name="DBusSubtreeIntrospectFunc" c:type="GDBusSubtreeIntrospectFunc" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.</doc> + <type name="DBusInterfaceInfo" c:type="GDBusInterfaceInfo**"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="sender" transfer-ownership="none"> + <doc xml:space="preserve">The unique bus name of the remote caller.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object_path" transfer-ownership="none"> + <doc xml:space="preserve">The object path that was registered with g_dbus_connection_register_subtree().</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="node" transfer-ownership="none"> + <doc xml:space="preserve">A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">The @user_data #gpointer passed to g_dbus_connection_register_subtree().</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="DBusSubtreeVTable" c:type="GDBusSubtreeVTable" version="2.26"> + <doc xml:space="preserve">Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().</doc> + <field name="enumerate" introspectable="0" writable="1"> + <doc xml:space="preserve">Function for enumerating child nodes.</doc> + <type name="DBusSubtreeEnumerateFunc" c:type="GDBusSubtreeEnumerateFunc"/> + </field> + <field name="introspect" writable="1"> + <doc xml:space="preserve">Function for introspecting a child node.</doc> + <type name="DBusSubtreeIntrospectFunc" c:type="GDBusSubtreeIntrospectFunc"/> + </field> + <field name="dispatch" writable="1"> + <doc xml:space="preserve">Function for dispatching a remote call on a child node.</doc> + <type name="DBusSubtreeDispatchFunc" c:type="GDBusSubtreeDispatchFunc"/> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="8"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <function-macro name="DESKTOP_APP_INFO" c:identifier="G_DESKTOP_APP_INFO" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DESKTOP_APP_INFO_CLASS" c:identifier="G_DESKTOP_APP_INFO_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DESKTOP_APP_INFO_GET_CLASS" c:identifier="G_DESKTOP_APP_INFO_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DESKTOP_APP_INFO_LOOKUP" c:identifier="G_DESKTOP_APP_INFO_LOOKUP" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <constant name="DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME" value="gio-desktop-app-info-lookup" c:type="G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME" deprecated="1" deprecated-version="2.28"> + <doc xml:space="preserve">Extension point for default handler to URI association. See +[Extending GIO][extending-gio].</doc> + <doc-deprecated xml:space="preserve">The #GDesktopAppInfoLookup interface is deprecated and + unused by GIO.</doc-deprecated> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="DESKTOP_APP_INFO_LOOKUP_GET_IFACE" c:identifier="G_DESKTOP_APP_INFO_LOOKUP_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DRIVE" c:identifier="G_DRIVE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DRIVE_GET_IFACE" c:identifier="G_DRIVE_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <constant name="DRIVE_IDENTIFIER_KIND_UNIX_DEVICE" value="unix-device" c:type="G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE" version="2.58"> + <doc xml:space="preserve">The string used to obtain a Unix device path with g_drive_get_identifier().</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="DTLS_CLIENT_CONNECTION" c:identifier="G_DTLS_CLIENT_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DTLS_CLIENT_CONNECTION_GET_INTERFACE" c:identifier="G_DTLS_CLIENT_CONNECTION_GET_INTERFACE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DTLS_CONNECTION" c:identifier="G_DTLS_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DTLS_CONNECTION_GET_INTERFACE" c:identifier="G_DTLS_CONNECTION_GET_INTERFACE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DTLS_SERVER_CONNECTION" c:identifier="G_DTLS_SERVER_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="DTLS_SERVER_CONNECTION_GET_INTERFACE" c:identifier="G_DTLS_SERVER_CONNECTION_GET_INTERFACE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <class name="DataInputStream" c:symbol-prefix="data_input_stream" c:type="GDataInputStream" parent="BufferedInputStream" glib:type-name="GDataInputStream" glib:get-type="g_data_input_stream_get_type" glib:type-struct="DataInputStreamClass"> + <doc xml:space="preserve">Data input stream implements #GInputStream and includes functions for +reading structured data directly from a binary input stream.</doc> + <implements name="Seekable"/> + <constructor name="new" c:identifier="g_data_input_stream_new"> + <doc xml:space="preserve">Creates a new data input stream for the @base_stream.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </return-value> + <parameters> + <parameter name="base_stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + </parameters> + </constructor> + <method name="get_byte_order" c:identifier="g_data_input_stream_get_byte_order"> + <doc xml:space="preserve">Gets the byte order for the data input stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the @stream's current #GDataStreamByteOrder.</doc> + <type name="DataStreamByteOrder" c:type="GDataStreamByteOrder"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_newline_type" c:identifier="g_data_input_stream_get_newline_type"> + <doc xml:space="preserve">Gets the current newline type for the @stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">#GDataStreamNewlineType for the given @stream.</doc> + <type name="DataStreamNewlineType" c:type="GDataStreamNewlineType"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="read_byte" c:identifier="g_data_input_stream_read_byte" throws="1"> + <doc xml:space="preserve">Reads an unsigned 8-bit/1-byte value from @stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an unsigned 8-bit/1-byte value read from the @stream or `0` +if an error occurred.</doc> + <type name="guint8" c:type="guchar"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_int16" c:identifier="g_data_input_stream_read_int16" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a signed 16-bit/2-byte value read from @stream or `0` if +an error occurred.</doc> + <type name="gint16" c:type="gint16"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_int32" c:identifier="g_data_input_stream_read_int32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a signed 32-bit/4-byte value read from the @stream or `0` if +an error occurred.</doc> + <type name="gint32" c:type="gint32"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_int64" c:identifier="g_data_input_stream_read_int64" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a signed 64-bit/8-byte value read from @stream or `0` if +an error occurred.</doc> + <type name="gint64" c:type="gint64"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_line" c:identifier="g_data_input_stream_read_line" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve"> + 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.</doc> + <array c:type="char*"> + <type name="guint8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a #gsize to get the length of the data read in.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_line_async" c:identifier="g_data_input_stream_read_line_async" version="2.20"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call when the request is satisfied.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="read_line_finish" c:identifier="g_data_input_stream_read_line_finish" version="2.20" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve"> + 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.</doc> + <array c:type="char*"> + <type name="guint8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult that was provided to the callback.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a #gsize to get the length of the data read in.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="read_line_finish_utf8" c:identifier="g_data_input_stream_read_line_finish_utf8" version="2.30" throws="1"> + <doc xml:space="preserve">Finish an asynchronous call started by +g_data_input_stream_read_line_async().</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult that was provided to the callback.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a #gsize to get the length of the data read in.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="read_line_utf8" c:identifier="g_data_input_stream_read_line_utf8" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a #gsize to get the length of the data read in.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_uint16" c:identifier="g_data_input_stream_read_uint16" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an unsigned 16-bit/2-byte value read from the @stream or `0` if +an error occurred.</doc> + <type name="guint16" c:type="guint16"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_uint32" c:identifier="g_data_input_stream_read_uint32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an unsigned 32-bit/4-byte value read from the @stream or `0` if +an error occurred.</doc> + <type name="guint32" c:type="guint32"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_uint64" c:identifier="g_data_input_stream_read_uint64" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an unsigned 64-bit/8-byte read from @stream or `0` if +an error occurred.</doc> + <type name="guint64" c:type="guint64"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_until" c:identifier="g_data_input_stream_read_until" deprecated="1" deprecated-version="2.56" throws="1"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_data_input_stream_read_upto() instead, which has more + consistent behaviour regarding the stop character.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="stop_chars" transfer-ownership="none"> + <doc xml:space="preserve">characters to terminate the read.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a #gsize to get the length of the data read in.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_until_async" c:identifier="g_data_input_stream_read_until_async" version="2.20" deprecated="1" deprecated-version="2.56"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_data_input_stream_read_upto_async() instead, which + has more consistent behaviour regarding the stop character.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="stop_chars" transfer-ownership="none"> + <doc xml:space="preserve">characters to terminate the read.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call when the request is satisfied.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="read_until_finish" c:identifier="g_data_input_stream_read_until_finish" version="2.20" deprecated="1" deprecated-version="2.56" throws="1"> + <doc xml:space="preserve">Finish an asynchronous call started by +g_data_input_stream_read_until_async().</doc> + <doc-deprecated xml:space="preserve">Use g_data_input_stream_read_upto_finish() instead, which + has more consistent behaviour regarding the stop character.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult that was provided to the callback.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a #gsize to get the length of the data read in.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="read_upto" c:identifier="g_data_input_stream_read_upto" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GDataInputStream</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="stop_chars" transfer-ownership="none"> + <doc xml:space="preserve">characters to terminate the read</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="stop_chars_len" transfer-ownership="none"> + <doc xml:space="preserve">length of @stop_chars. May be -1 if @stop_chars is + nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a #gsize to get the length of the data read in</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_upto_async" c:identifier="g_data_input_stream_read_upto_async" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GDataInputStream</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="stop_chars" transfer-ownership="none"> + <doc xml:space="preserve">characters to terminate the read</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="stop_chars_len" transfer-ownership="none"> + <doc xml:space="preserve">length of @stop_chars. May be -1 if @stop_chars is + nul-terminated</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="read_upto_finish" c:identifier="g_data_input_stream_read_upto_finish" version="2.24" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GDataInputStream</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult that was provided to the callback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a #gsize to get the length of the data read in</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="set_byte_order" c:identifier="g_data_input_stream_set_byte_order"> + <doc xml:space="preserve">This function sets the byte order for the given @stream. All subsequent +reads from the @stream will be read in the given @order.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a given #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="order" transfer-ownership="none"> + <doc xml:space="preserve">a #GDataStreamByteOrder to set.</doc> + <type name="DataStreamByteOrder" c:type="GDataStreamByteOrder"/> + </parameter> + </parameters> + </method> + <method name="set_newline_type" c:identifier="g_data_input_stream_set_newline_type"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GDataInputStream.</doc> + <type name="DataInputStream" c:type="GDataInputStream*"/> + </instance-parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">the type of new line return as #GDataStreamNewlineType.</doc> + <type name="DataStreamNewlineType" c:type="GDataStreamNewlineType"/> + </parameter> + </parameters> + </method> + <property name="byte-order" writable="1" transfer-ownership="none"> + <type name="DataStreamByteOrder"/> + </property> + <property name="newline-type" writable="1" transfer-ownership="none"> + <type name="DataStreamNewlineType"/> + </property> + <field name="parent_instance"> + <type name="BufferedInputStream" c:type="GBufferedInputStream"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="DataInputStreamPrivate" c:type="GDataInputStreamPrivate*"/> + </field> + </class> + <record name="DataInputStreamClass" c:type="GDataInputStreamClass" glib:is-gtype-struct-for="DataInputStream"> + <field name="parent_class"> + <type name="BufferedInputStreamClass" c:type="GBufferedInputStreamClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="DataInputStreamPrivate" c:type="GDataInputStreamPrivate" disguised="1"/> + <class name="DataOutputStream" c:symbol-prefix="data_output_stream" c:type="GDataOutputStream" parent="FilterOutputStream" glib:type-name="GDataOutputStream" glib:get-type="g_data_output_stream_get_type" glib:type-struct="DataOutputStreamClass"> + <doc xml:space="preserve">Data output stream implements #GOutputStream and includes functions for +writing data directly to an output stream.</doc> + <implements name="Seekable"/> + <constructor name="new" c:identifier="g_data_output_stream_new"> + <doc xml:space="preserve">Creates a new data output stream for @base_stream.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GDataOutputStream.</doc> + <type name="DataOutputStream" c:type="GDataOutputStream*"/> + </return-value> + <parameters> + <parameter name="base_stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + </parameters> + </constructor> + <method name="get_byte_order" c:identifier="g_data_output_stream_get_byte_order"> + <doc xml:space="preserve">Gets the byte order for the stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GDataStreamByteOrder for the @stream.</doc> + <type name="DataStreamByteOrder" c:type="GDataStreamByteOrder"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GDataOutputStream.</doc> + <type name="DataOutputStream" c:type="GDataOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="put_byte" c:identifier="g_data_output_stream_put_byte" throws="1"> + <doc xml:space="preserve">Puts a byte into the output stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @data was successfully added to the @stream.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GDataOutputStream.</doc> + <type name="DataOutputStream" c:type="GDataOutputStream*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">a #guchar.</doc> + <type name="guint8" c:type="guchar"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="put_int16" c:identifier="g_data_output_stream_put_int16" throws="1"> + <doc xml:space="preserve">Puts a signed 16-bit integer into the output stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @data was successfully added to the @stream.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GDataOutputStream.</doc> + <type name="DataOutputStream" c:type="GDataOutputStream*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">a #gint16.</doc> + <type name="gint16" c:type="gint16"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="put_int32" c:identifier="g_data_output_stream_put_int32" throws="1"> + <doc xml:space="preserve">Puts a signed 32-bit integer into the output stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @data was successfully added to the @stream.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GDataOutputStream.</doc> + <type name="DataOutputStream" c:type="GDataOutputStream*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">a #gint32.</doc> + <type name="gint32" c:type="gint32"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="put_int64" c:identifier="g_data_output_stream_put_int64" throws="1"> + <doc xml:space="preserve">Puts a signed 64-bit integer into the stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @data was successfully added to the @stream.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GDataOutputStream.</doc> + <type name="DataOutputStream" c:type="GDataOutputStream*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">a #gint64.</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="put_string" c:identifier="g_data_output_stream_put_string" throws="1"> + <doc xml:space="preserve">Puts a string into the output stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @string was successfully added to the @stream.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GDataOutputStream.</doc> + <type name="DataOutputStream" c:type="GDataOutputStream*"/> + </instance-parameter> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">a string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="put_uint16" c:identifier="g_data_output_stream_put_uint16" throws="1"> + <doc xml:space="preserve">Puts an unsigned 16-bit integer into the output stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @data was successfully added to the @stream.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GDataOutputStream.</doc> + <type name="DataOutputStream" c:type="GDataOutputStream*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">a #guint16.</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="put_uint32" c:identifier="g_data_output_stream_put_uint32" throws="1"> + <doc xml:space="preserve">Puts an unsigned 32-bit integer into the stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @data was successfully added to the @stream.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GDataOutputStream.</doc> + <type name="DataOutputStream" c:type="GDataOutputStream*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">a #guint32.</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="put_uint64" c:identifier="g_data_output_stream_put_uint64" throws="1"> + <doc xml:space="preserve">Puts an unsigned 64-bit integer into the stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @data was successfully added to the @stream.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GDataOutputStream.</doc> + <type name="DataOutputStream" c:type="GDataOutputStream*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">a #guint64.</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_byte_order" c:identifier="g_data_output_stream_set_byte_order"> + <doc xml:space="preserve">Sets the byte order of the data output stream to @order.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GDataOutputStream.</doc> + <type name="DataOutputStream" c:type="GDataOutputStream*"/> + </instance-parameter> + <parameter name="order" transfer-ownership="none"> + <doc xml:space="preserve">a %GDataStreamByteOrder.</doc> + <type name="DataStreamByteOrder" c:type="GDataStreamByteOrder"/> + </parameter> + </parameters> + </method> + <property name="byte-order" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">Determines the byte ordering that is used when writing +multi-byte entities (such as integers) to the stream.</doc> + <type name="DataStreamByteOrder"/> + </property> + <field name="parent_instance"> + <type name="FilterOutputStream" c:type="GFilterOutputStream"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="DataOutputStreamPrivate" c:type="GDataOutputStreamPrivate*"/> + </field> + </class> + <record name="DataOutputStreamClass" c:type="GDataOutputStreamClass" glib:is-gtype-struct-for="DataOutputStream"> + <field name="parent_class"> + <type name="FilterOutputStreamClass" c:type="GFilterOutputStreamClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="DataOutputStreamPrivate" c:type="GDataOutputStreamPrivate" disguised="1"/> + <enumeration name="DataStreamByteOrder" glib:type-name="GDataStreamByteOrder" glib:get-type="g_data_stream_byte_order_get_type" c:type="GDataStreamByteOrder"> + <doc xml:space="preserve">#GDataStreamByteOrder is used to ensure proper endianness of streaming data sources +across various machine architectures.</doc> + <member name="big_endian" value="0" c:identifier="G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN" glib:nick="big-endian"> + <doc xml:space="preserve">Selects Big Endian byte order.</doc> + </member> + <member name="little_endian" value="1" c:identifier="G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN" glib:nick="little-endian"> + <doc xml:space="preserve">Selects Little Endian byte order.</doc> + </member> + <member name="host_endian" value="2" c:identifier="G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN" glib:nick="host-endian"> + <doc xml:space="preserve">Selects endianness based on host machine's architecture.</doc> + </member> + </enumeration> + <enumeration name="DataStreamNewlineType" glib:type-name="GDataStreamNewlineType" glib:get-type="g_data_stream_newline_type_get_type" c:type="GDataStreamNewlineType"> + <doc xml:space="preserve">#GDataStreamNewlineType is used when checking for or setting the line endings for a given file.</doc> + <member name="lf" value="0" c:identifier="G_DATA_STREAM_NEWLINE_TYPE_LF" glib:nick="lf"> + <doc xml:space="preserve">Selects "LF" line endings, common on most modern UNIX platforms.</doc> + </member> + <member name="cr" value="1" c:identifier="G_DATA_STREAM_NEWLINE_TYPE_CR" glib:nick="cr"> + <doc xml:space="preserve">Selects "CR" line endings.</doc> + </member> + <member name="cr_lf" value="2" c:identifier="G_DATA_STREAM_NEWLINE_TYPE_CR_LF" glib:nick="cr-lf"> + <doc xml:space="preserve">Selects "CR, LF" line ending, common on Microsoft Windows.</doc> + </member> + <member name="any" value="3" c:identifier="G_DATA_STREAM_NEWLINE_TYPE_ANY" glib:nick="any"> + <doc xml:space="preserve">Automatically try to handle any line ending type.</doc> + </member> + </enumeration> + <interface name="DatagramBased" c:symbol-prefix="datagram_based" c:type="GDatagramBased" version="2.48" glib:type-name="GDatagramBased" glib:get-type="g_datagram_based_get_type" glib:type-struct="DatagramBasedInterface"> + <doc xml:space="preserve">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.</doc> + <virtual-method name="condition_check" invoker="condition_check" version="2.48"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GIOCondition mask of the current state</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </return-value> + <parameters> + <instance-parameter name="datagram_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GDatagramBased</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </instance-parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOCondition mask to check</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="condition_wait" invoker="condition_wait" version="2.48" throws="1"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the condition was met, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="datagram_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GDatagramBased</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </instance-parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOCondition mask to wait for</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="timeout" transfer-ownership="none"> + <doc xml:space="preserve">the maximum time (in microseconds) to wait, 0 to not block, or -1 + to block indefinitely</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="create_source" invoker="create_source" version="2.48"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated #GSource</doc> + <type name="GLib.Source" c:type="GSource*"/> + </return-value> + <parameters> + <instance-parameter name="datagram_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GDatagramBased</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </instance-parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOCondition mask to monitor</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="receive_messages" invoker="receive_messages" version="2.48" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="datagram_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GDatagramBased</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </instance-parameter> + <parameter name="messages" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GInputMessage structs</doc> + <array length="1" zero-terminated="0" c:type="GInputMessage*"> + <type name="InputMessage" c:type="GInputMessage"/> + </array> + </parameter> + <parameter name="num_messages" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements in @messages</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">an int containing #GSocketMsgFlags flags for the overall operation</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="timeout" transfer-ownership="none"> + <doc xml:space="preserve">the maximum time (in microseconds) to wait, 0 to not block, or -1 + to block indefinitely</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="send_messages" invoker="send_messages" version="2.48" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="datagram_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GDatagramBased</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </instance-parameter> + <parameter name="messages" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GOutputMessage structs</doc> + <array length="1" zero-terminated="0" c:type="GOutputMessage*"> + <type name="OutputMessage" c:type="GOutputMessage"/> + </array> + </parameter> + <parameter name="num_messages" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements in @messages</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">an int containing #GSocketMsgFlags flags</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="timeout" transfer-ownership="none"> + <doc xml:space="preserve">the maximum time (in microseconds) to wait, 0 to not block, or -1 + to block indefinitely</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <method name="condition_check" c:identifier="g_datagram_based_condition_check" version="2.48"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GIOCondition mask of the current state</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </return-value> + <parameters> + <instance-parameter name="datagram_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GDatagramBased</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </instance-parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOCondition mask to check</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </parameter> + </parameters> + </method> + <method name="condition_wait" c:identifier="g_datagram_based_condition_wait" version="2.48" throws="1"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the condition was met, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="datagram_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GDatagramBased</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </instance-parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOCondition mask to wait for</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="timeout" transfer-ownership="none"> + <doc xml:space="preserve">the maximum time (in microseconds) to wait, 0 to not block, or -1 + to block indefinitely</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="create_source" c:identifier="g_datagram_based_create_source" version="2.48"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated #GSource</doc> + <type name="GLib.Source" c:type="GSource*"/> + </return-value> + <parameters> + <instance-parameter name="datagram_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GDatagramBased</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </instance-parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOCondition mask to monitor</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="receive_messages" c:identifier="g_datagram_based_receive_messages" version="2.48" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="datagram_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GDatagramBased</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </instance-parameter> + <parameter name="messages" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GInputMessage structs</doc> + <array length="1" zero-terminated="0" c:type="GInputMessage*"> + <type name="InputMessage" c:type="GInputMessage"/> + </array> + </parameter> + <parameter name="num_messages" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements in @messages</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">an int containing #GSocketMsgFlags flags for the overall operation</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="timeout" transfer-ownership="none"> + <doc xml:space="preserve">the maximum time (in microseconds) to wait, 0 to not block, or -1 + to block indefinitely</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="send_messages" c:identifier="g_datagram_based_send_messages" version="2.48" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="datagram_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GDatagramBased</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </instance-parameter> + <parameter name="messages" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GOutputMessage structs</doc> + <array length="1" zero-terminated="0" c:type="GOutputMessage*"> + <type name="OutputMessage" c:type="GOutputMessage"/> + </array> + </parameter> + <parameter name="num_messages" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements in @messages</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">an int containing #GSocketMsgFlags flags</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="timeout" transfer-ownership="none"> + <doc xml:space="preserve">the maximum time (in microseconds) to wait, 0 to not block, or -1 + to block indefinitely</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + </interface> + <record name="DatagramBasedInterface" c:type="GDatagramBasedInterface" glib:is-gtype-struct-for="DatagramBased" version="2.48"> + <doc xml:space="preserve">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.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="receive_messages"> + <callback name="receive_messages" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="datagram_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GDatagramBased</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </parameter> + <parameter name="messages" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GInputMessage structs</doc> + <array length="2" zero-terminated="0" c:type="GInputMessage*"> + <type name="InputMessage" c:type="GInputMessage"/> + </array> + </parameter> + <parameter name="num_messages" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements in @messages</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">an int containing #GSocketMsgFlags flags for the overall operation</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="timeout" transfer-ownership="none"> + <doc xml:space="preserve">the maximum time (in microseconds) to wait, 0 to not block, or -1 + to block indefinitely</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="send_messages"> + <callback name="send_messages" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="datagram_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GDatagramBased</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </parameter> + <parameter name="messages" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GOutputMessage structs</doc> + <array length="2" zero-terminated="0" c:type="GOutputMessage*"> + <type name="OutputMessage" c:type="GOutputMessage"/> + </array> + </parameter> + <parameter name="num_messages" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements in @messages</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">an int containing #GSocketMsgFlags flags</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="timeout" transfer-ownership="none"> + <doc xml:space="preserve">the maximum time (in microseconds) to wait, 0 to not block, or -1 + to block indefinitely</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="create_source"> + <callback name="create_source"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated #GSource</doc> + <type name="GLib.Source" c:type="GSource*"/> + </return-value> + <parameters> + <parameter name="datagram_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GDatagramBased</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOCondition mask to monitor</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="condition_check"> + <callback name="condition_check"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GIOCondition mask of the current state</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </return-value> + <parameters> + <parameter name="datagram_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GDatagramBased</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOCondition mask to check</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </parameter> + </parameters> + </callback> + </field> + <field name="condition_wait"> + <callback name="condition_wait" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the condition was met, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="datagram_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GDatagramBased</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOCondition mask to wait for</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="timeout" transfer-ownership="none"> + <doc xml:space="preserve">the maximum time (in microseconds) to wait, 0 to not block, or -1 + to block indefinitely</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <callback name="DatagramBasedSourceFunc" c:type="GDatagramBasedSourceFunc" version="2.48"> + <doc xml:space="preserve">This is the function type of the callback used for the #GSource +returned by g_datagram_based_create_source().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%G_SOURCE_REMOVE if the source should be removed, + %G_SOURCE_CONTINUE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="datagram_based" transfer-ownership="none"> + <doc xml:space="preserve">the #GDatagramBased</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">the current condition at the source fired</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">data passed in by the user</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <class name="DesktopAppInfo" c:symbol-prefix="desktop_app_info" c:type="GDesktopAppInfo" parent="GObject.Object" glib:type-name="GDesktopAppInfo" glib:get-type="g_desktop_app_info_get_type" glib:type-struct="DesktopAppInfoClass"> + <doc xml:space="preserve">#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.</doc> + <implements name="AppInfo"/> + <constructor name="new" c:identifier="g_desktop_app_info_new"> + <doc xml:space="preserve">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`).</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new #GDesktopAppInfo, or %NULL if no desktop + file with that id exists.</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </return-value> + <parameters> + <parameter name="desktop_id" transfer-ownership="none"> + <doc xml:space="preserve">the desktop file id</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_filename" c:identifier="g_desktop_app_info_new_from_filename"> + <doc xml:space="preserve">Creates a new #GDesktopAppInfo.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new #GDesktopAppInfo or %NULL on error.</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">the path of a desktop file, in the GLib + filename encoding</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_keyfile" c:identifier="g_desktop_app_info_new_from_keyfile" version="2.18"> + <doc xml:space="preserve">Creates a new #GDesktopAppInfo.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new #GDesktopAppInfo or %NULL on error.</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </return-value> + <parameters> + <parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">an opened #GKeyFile</doc> + <type name="GLib.KeyFile" c:type="GKeyFile*"/> + </parameter> + </parameters> + </constructor> + <function name="get_implementations" c:identifier="g_desktop_app_info_get_implementations" version="2.42"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a list of #GDesktopAppInfo +objects.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="DesktopAppInfo"/> + </type> + </return-value> + <parameters> + <parameter name="interface" transfer-ownership="none"> + <doc xml:space="preserve">the name of the interface</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="search" c:identifier="g_desktop_app_info_search"> + <doc xml:space="preserve">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. + +None of the search results are subjected to the normal validation +checks performed by g_desktop_app_info_new() (for example, checking that +the executable referenced by a result exists), and so it is possible for +g_desktop_app_info_new() to return %NULL when passed an app ID returned by +this function. It is expected that calling code will do this when +subsequently creating a #GDesktopAppInfo for each result.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a + list of strvs. Free each item with g_strfreev() and free the outer + list with g_free().</doc> + <array c:type="gchar***"> + <array> + <type name="utf8"/> + </array> + </array> + </return-value> + <parameters> + <parameter name="search_string" transfer-ownership="none"> + <doc xml:space="preserve">the search string to use</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="set_desktop_env" c:identifier="g_desktop_app_info_set_desktop_env" deprecated="1" deprecated-version="2.42"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">do not use this API. Since 2.42 the value of the +`XDG_CURRENT_DESKTOP` environment variable will be used.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="desktop_env" transfer-ownership="none"> + <doc xml:space="preserve">a string specifying what desktop this is</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <method name="get_action_name" c:identifier="g_desktop_app_info_get_action_name" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the locale-specific action name</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action as from + g_desktop_app_info_list_actions()</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_boolean" c:identifier="g_desktop_app_info_get_boolean" version="2.36"> + <doc xml:space="preserve">Looks up a boolean value in the keyfile backing @info. + +The @key is looked up in the "Desktop Entry" group.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the boolean value, or %FALSE if the key + is not found</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to look up</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_categories" c:identifier="g_desktop_app_info_get_categories"> + <doc xml:space="preserve">Gets the categories from the desktop file.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The unparsed Categories key from the desktop file; + i.e. no attempt is made to split it by ';' or validate it.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_filename" c:identifier="g_desktop_app_info_get_filename" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The full path to the file for @info, + or %NULL if not known.</doc> + <type name="filename" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_generic_name" c:identifier="g_desktop_app_info_get_generic_name"> + <doc xml:space="preserve">Gets the generic name from the desktop file.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The value of the GenericName key</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_hidden" c:identifier="g_desktop_app_info_get_is_hidden"> + <doc xml:space="preserve">A desktop file is hidden if the Hidden key in it is +set to True.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if hidden, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo.</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_keywords" c:identifier="g_desktop_app_info_get_keywords" version="2.32"> + <doc xml:space="preserve">Gets the keywords from the desktop file.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The value of the Keywords key</doc> + <array c:type="const char* const*"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_locale_string" c:identifier="g_desktop_app_info_get_locale_string" version="2.56"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly allocated string, or %NULL if the key + is not found</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to look up</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_nodisplay" c:identifier="g_desktop_app_info_get_nodisplay" version="2.30"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The value of the NoDisplay key</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_show_in" c:identifier="g_desktop_app_info_get_show_in" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @info should be shown in @desktop_env according to the +`OnlyShowIn` and `NotShowIn` keys, %FALSE +otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + <parameter name="desktop_env" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string specifying a desktop name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_startup_wm_class" c:identifier="g_desktop_app_info_get_startup_wm_class" version="2.34"> + <doc xml:space="preserve">Retrieves the StartupWMClass field from @info. This represents the +WM_CLASS property of the main window of the application, if launched +through @info.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the startup WM class, or %NULL if none is set +in the desktop file.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo that supports startup notify</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_string" c:identifier="g_desktop_app_info_get_string" version="2.36"> + <doc xml:space="preserve">Looks up a string value in the keyfile backing @info. + +The @key is looked up in the "Desktop Entry" group.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly allocated string, or %NULL if the key + is not found</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to look up</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_string_list" c:identifier="g_desktop_app_info_get_string_list" version="2.60"> + <doc xml:space="preserve">Looks up a string list value in the keyfile backing @info. + +The @key is looked up in the "Desktop Entry" group.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + a %NULL-terminated string array or %NULL if the specified + key cannot be found. The array should be freed with g_strfreev().</doc> + <array length="1" zero-terminated="1" c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to look up</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the number of returned strings, or %NULL</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="has_key" c:identifier="g_desktop_app_info_has_key" version="2.36"> + <doc xml:space="preserve">Returns whether @key exists in the "Desktop Entry" group +of the keyfile backing @info.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @key exists</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to look up</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="launch_action" c:identifier="g_desktop_app_info_launch_action" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action as from + g_desktop_app_info_list_actions()</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="launch_context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GAppLaunchContext</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + </parameters> + </method> + <method name="launch_uris_as_manager" c:identifier="g_desktop_app_info_launch_uris_as_manager" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful launch, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + <parameter name="uris" transfer-ownership="none"> + <doc xml:space="preserve">List of URIs</doc> + <type name="GLib.List" c:type="GList*"> + <type name="utf8"/> + </type> + </parameter> + <parameter name="launch_context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GAppLaunchContext</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + <parameter name="spawn_flags" transfer-ownership="none"> + <doc xml:space="preserve">#GSpawnFlags, used for each process</doc> + <type name="GLib.SpawnFlags" c:type="GSpawnFlags"/> + </parameter> + <parameter name="user_setup" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GSpawnChildSetupFunc, used once + for each process.</doc> + <type name="GLib.SpawnChildSetupFunc" c:type="GSpawnChildSetupFunc"/> + </parameter> + <parameter name="user_setup_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">User data for @user_setup</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="pid_callback" transfer-ownership="none" nullable="1" allow-none="1" scope="call" closure="6"> + <doc xml:space="preserve">Callback for child processes</doc> + <type name="DesktopAppLaunchCallback" c:type="GDesktopAppLaunchCallback"/> + </parameter> + <parameter name="pid_callback_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">User data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="launch_uris_as_manager_with_fds" c:identifier="g_desktop_app_info_launch_uris_as_manager_with_fds" version="2.58" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful launch, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + <parameter name="uris" transfer-ownership="none"> + <doc xml:space="preserve">List of URIs</doc> + <type name="GLib.List" c:type="GList*"> + <type name="utf8"/> + </type> + </parameter> + <parameter name="launch_context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GAppLaunchContext</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + <parameter name="spawn_flags" transfer-ownership="none"> + <doc xml:space="preserve">#GSpawnFlags, used for each process</doc> + <type name="GLib.SpawnFlags" c:type="GSpawnFlags"/> + </parameter> + <parameter name="user_setup" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GSpawnChildSetupFunc, used once + for each process.</doc> + <type name="GLib.SpawnChildSetupFunc" c:type="GSpawnChildSetupFunc"/> + </parameter> + <parameter name="user_setup_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">User data for @user_setup</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="pid_callback" transfer-ownership="none" nullable="1" allow-none="1" scope="call" closure="6"> + <doc xml:space="preserve">Callback for child processes</doc> + <type name="DesktopAppLaunchCallback" c:type="GDesktopAppLaunchCallback"/> + </parameter> + <parameter name="pid_callback_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">User data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="stdin_fd" transfer-ownership="none"> + <doc xml:space="preserve">file descriptor to use for child's stdin, or -1</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="stdout_fd" transfer-ownership="none"> + <doc xml:space="preserve">file descriptor to use for child's stdout, or -1</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="stderr_fd" transfer-ownership="none"> + <doc xml:space="preserve">file descriptor to use for child's stderr, or -1</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="list_actions" c:identifier="g_desktop_app_info_list_actions" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a list of strings, always non-%NULL</doc> + <array c:type="const gchar* const*"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </instance-parameter> + </parameters> + </method> + <property name="filename" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The origin filename of this #GDesktopAppInfo</doc> + <type name="utf8" c:type="gchar*"/> + </property> + </class> + <record name="DesktopAppInfoClass" c:type="GDesktopAppInfoClass" glib:is-gtype-struct-for="DesktopAppInfo"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <interface name="DesktopAppInfoLookup" c:symbol-prefix="desktop_app_info_lookup" c:type="GDesktopAppInfoLookup" deprecated="1" deprecated-version="2.28" glib:type-name="GDesktopAppInfoLookup" glib:get-type="g_desktop_app_info_lookup_get_type" glib:type-struct="DesktopAppInfoLookupIface"> + <doc xml:space="preserve">#GDesktopAppInfoLookup is an opaque data structure and can only be accessed +using the following functions.</doc> + <doc-deprecated xml:space="preserve">The #GDesktopAppInfoLookup interface is deprecated and + unused by GIO.</doc-deprecated> + <virtual-method name="get_default_for_uri_scheme" invoker="get_default_for_uri_scheme" deprecated="1" deprecated-version="2.28"> + <doc xml:space="preserve">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().</doc> + <doc-deprecated xml:space="preserve">The #GDesktopAppInfoLookup interface is deprecated and + unused by GIO.</doc-deprecated> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">#GAppInfo for given @uri_scheme or + %NULL on error.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </return-value> + <parameters> + <instance-parameter name="lookup" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfoLookup</doc> + <type name="DesktopAppInfoLookup" c:type="GDesktopAppInfoLookup*"/> + </instance-parameter> + <parameter name="uri_scheme" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a URI scheme.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_default_for_uri_scheme" c:identifier="g_desktop_app_info_lookup_get_default_for_uri_scheme" deprecated="1" deprecated-version="2.28"> + <doc xml:space="preserve">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().</doc> + <doc-deprecated xml:space="preserve">The #GDesktopAppInfoLookup interface is deprecated and + unused by GIO.</doc-deprecated> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">#GAppInfo for given @uri_scheme or + %NULL on error.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </return-value> + <parameters> + <instance-parameter name="lookup" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfoLookup</doc> + <type name="DesktopAppInfoLookup" c:type="GDesktopAppInfoLookup*"/> + </instance-parameter> + <parameter name="uri_scheme" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a URI scheme.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + </interface> + <record name="DesktopAppInfoLookupIface" c:type="GDesktopAppInfoLookupIface" glib:is-gtype-struct-for="DesktopAppInfoLookup"> + <doc xml:space="preserve">Interface that is used by backends to associate default +handlers with URI schemes.</doc> + <field name="g_iface"> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="get_default_for_uri_scheme"> + <callback name="get_default_for_uri_scheme"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">#GAppInfo for given @uri_scheme or + %NULL on error.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </return-value> + <parameters> + <parameter name="lookup" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfoLookup</doc> + <type name="DesktopAppInfoLookup" c:type="GDesktopAppInfoLookup*"/> + </parameter> + <parameter name="uri_scheme" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a URI scheme.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <callback name="DesktopAppLaunchCallback" c:type="GDesktopAppLaunchCallback"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="appinfo" transfer-ownership="none"> + <doc xml:space="preserve">a #GDesktopAppInfo</doc> + <type name="DesktopAppInfo" c:type="GDesktopAppInfo*"/> + </parameter> + <parameter name="pid" transfer-ownership="none"> + <doc xml:space="preserve">Process identifier</doc> + <type name="GLib.Pid" c:type="GPid"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">User data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <interface name="Drive" c:symbol-prefix="drive" c:type="GDrive" glib:type-name="GDrive" glib:get-type="g_drive_get_type" glib:type-struct="DriveIface"> + <doc xml:space="preserve">#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 potentially 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.</doc> + <virtual-method name="can_eject" invoker="can_eject"> + <doc xml:space="preserve">Checks if a drive can be ejected.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive can be ejected, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="can_poll_for_media" invoker="can_poll_for_media"> + <doc xml:space="preserve">Checks if a drive can be polled for media changes.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive can be polled for media changes, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="can_start" invoker="can_start" version="2.22"> + <doc xml:space="preserve">Checks if a drive can be started.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive can be started, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="can_start_degraded" invoker="can_start_degraded" version="2.22"> + <doc xml:space="preserve">Checks if a drive can be started degraded.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive can be started degraded, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="can_stop" invoker="can_stop" version="2.22"> + <doc xml:space="preserve">Checks if a drive can be stopped.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive can be stopped, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="disconnected"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="eject" invoker="eject" deprecated="1" deprecated-version="2.22"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_drive_eject_with_operation() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="eject_button"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="eject_finish" invoker="eject_finish" deprecated="1" deprecated-version="2.22" throws="1"> + <doc xml:space="preserve">Finishes ejecting a drive.</doc> + <doc-deprecated xml:space="preserve">Use g_drive_eject_with_operation_finish() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the drive has been ejected successfully, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="eject_with_operation" invoker="eject_with_operation" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="eject_with_operation_finish" invoker="eject_with_operation_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes ejecting a drive. If any errors occurred during the operation, +@error will be set to contain the errors and %FALSE will be returned.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the drive was successfully ejected. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="enumerate_identifiers" invoker="enumerate_identifiers"> + <doc xml:space="preserve">Gets the kinds of identifiers that @drive has. +Use g_drive_get_identifier() to obtain the identifiers +themselves.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated + array of strings containing kinds of identifiers. Use g_strfreev() + to free.</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_icon" invoker="get_icon"> + <doc xml:space="preserve">Gets the icon for @drive.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GIcon for the @drive. + Free the returned object with g_object_unref().</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_identifier" invoker="get_identifier"> + <doc xml:space="preserve">Gets the identifier of the given kind for @drive. The only +identifier currently available is +#G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly allocated string containing the + requested identifier, or %NULL if the #GDrive + doesn't have this kind of identifier.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="kind" transfer-ownership="none"> + <doc xml:space="preserve">the kind of identifier to return</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_name" invoker="get_name"> + <doc xml:space="preserve">Gets the name of @drive.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a string containing @drive's name. The returned + string should be freed when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_sort_key" invoker="get_sort_key" version="2.32"> + <doc xml:space="preserve">Gets the sort key for @drive, if any.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">Sorting key for @drive or %NULL if no such key is available.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">A #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_start_stop_type" invoker="get_start_stop_type" version="2.22"> + <doc xml:space="preserve">Gets a hint about how a drive can be started/stopped.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A value from the #GDriveStartStopType enumeration.</doc> + <type name="DriveStartStopType" c:type="GDriveStartStopType"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_symbolic_icon" invoker="get_symbolic_icon" version="2.34"> + <doc xml:space="preserve">Gets the icon for @drive.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">symbolic #GIcon for the @drive. + Free the returned object with g_object_unref().</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_volumes" invoker="get_volumes"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GList containing any #GVolume objects on the given @drive.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="Volume"/> + </type> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="has_media" invoker="has_media"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @drive has media, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="has_volumes" invoker="has_volumes"> + <doc xml:space="preserve">Check if @drive has any mountable volumes.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive contains volumes, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="is_media_check_automatic" invoker="is_media_check_automatic"> + <doc xml:space="preserve">Checks if @drive is capable of automatically detecting media changes.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive is capable of automatically detecting + media changes, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="is_media_removable" invoker="is_media_removable"> + <doc xml:space="preserve">Checks if the @drive supports removable media.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @drive supports removable media, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="is_removable" invoker="is_removable" version="2.50"> + <doc xml:space="preserve">Checks if the #GDrive and/or its media is considered removable by the user. +See g_drive_is_media_removable().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @drive and/or its media is considered removable, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="poll_for_media" invoker="poll_for_media"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="poll_for_media_finish" invoker="poll_for_media_finish" throws="1"> + <doc xml:space="preserve">Finishes an operation started with g_drive_poll_for_media() on a drive.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the drive has been poll_for_mediaed successfully, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="start" invoker="start" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the start operation.</doc> + <type name="DriveStartFlags" c:type="GDriveStartFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="start_finish" invoker="start_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes starting a drive.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the drive has been started successfully, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="stop" invoker="stop" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for stopping.</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="stop_button"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="stop_finish" invoker="stop_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes stopping a drive.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the drive has been stopped successfully, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <method name="can_eject" c:identifier="g_drive_can_eject"> + <doc xml:space="preserve">Checks if a drive can be ejected.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive can be ejected, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="can_poll_for_media" c:identifier="g_drive_can_poll_for_media"> + <doc xml:space="preserve">Checks if a drive can be polled for media changes.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive can be polled for media changes, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="can_start" c:identifier="g_drive_can_start" version="2.22"> + <doc xml:space="preserve">Checks if a drive can be started.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive can be started, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="can_start_degraded" c:identifier="g_drive_can_start_degraded" version="2.22"> + <doc xml:space="preserve">Checks if a drive can be started degraded.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive can be started degraded, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="can_stop" c:identifier="g_drive_can_stop" version="2.22"> + <doc xml:space="preserve">Checks if a drive can be stopped.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive can be stopped, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="eject" c:identifier="g_drive_eject" deprecated="1" deprecated-version="2.22"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_drive_eject_with_operation() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="eject_finish" c:identifier="g_drive_eject_finish" deprecated="1" deprecated-version="2.22" throws="1"> + <doc xml:space="preserve">Finishes ejecting a drive.</doc> + <doc-deprecated xml:space="preserve">Use g_drive_eject_with_operation_finish() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the drive has been ejected successfully, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="eject_with_operation" c:identifier="g_drive_eject_with_operation" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="eject_with_operation_finish" c:identifier="g_drive_eject_with_operation_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes ejecting a drive. If any errors occurred during the operation, +@error will be set to contain the errors and %FALSE will be returned.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the drive was successfully ejected. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="enumerate_identifiers" c:identifier="g_drive_enumerate_identifiers"> + <doc xml:space="preserve">Gets the kinds of identifiers that @drive has. +Use g_drive_get_identifier() to obtain the identifiers +themselves.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated + array of strings containing kinds of identifiers. Use g_strfreev() + to free.</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_icon" c:identifier="g_drive_get_icon"> + <doc xml:space="preserve">Gets the icon for @drive.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GIcon for the @drive. + Free the returned object with g_object_unref().</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_identifier" c:identifier="g_drive_get_identifier"> + <doc xml:space="preserve">Gets the identifier of the given kind for @drive. The only +identifier currently available is +#G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly allocated string containing the + requested identifier, or %NULL if the #GDrive + doesn't have this kind of identifier.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="kind" transfer-ownership="none"> + <doc xml:space="preserve">the kind of identifier to return</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_name" c:identifier="g_drive_get_name"> + <doc xml:space="preserve">Gets the name of @drive.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a string containing @drive's name. The returned + string should be freed when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_sort_key" c:identifier="g_drive_get_sort_key" version="2.32"> + <doc xml:space="preserve">Gets the sort key for @drive, if any.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">Sorting key for @drive or %NULL if no such key is available.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">A #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_start_stop_type" c:identifier="g_drive_get_start_stop_type" version="2.22"> + <doc xml:space="preserve">Gets a hint about how a drive can be started/stopped.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A value from the #GDriveStartStopType enumeration.</doc> + <type name="DriveStartStopType" c:type="GDriveStartStopType"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_symbolic_icon" c:identifier="g_drive_get_symbolic_icon" version="2.34"> + <doc xml:space="preserve">Gets the icon for @drive.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">symbolic #GIcon for the @drive. + Free the returned object with g_object_unref().</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_volumes" c:identifier="g_drive_get_volumes"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GList containing any #GVolume objects on the given @drive.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="Volume"/> + </type> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="has_media" c:identifier="g_drive_has_media"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @drive has media, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="has_volumes" c:identifier="g_drive_has_volumes"> + <doc xml:space="preserve">Check if @drive has any mountable volumes.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive contains volumes, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_media_check_automatic" c:identifier="g_drive_is_media_check_automatic"> + <doc xml:space="preserve">Checks if @drive is capable of automatically detecting media changes.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive is capable of automatically detecting + media changes, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_media_removable" c:identifier="g_drive_is_media_removable"> + <doc xml:space="preserve">Checks if the @drive supports removable media.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @drive supports removable media, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_removable" c:identifier="g_drive_is_removable" version="2.50"> + <doc xml:space="preserve">Checks if the #GDrive and/or its media is considered removable by the user. +See g_drive_is_media_removable().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @drive and/or its media is considered removable, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + </parameters> + </method> + <method name="poll_for_media" c:identifier="g_drive_poll_for_media"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="poll_for_media_finish" c:identifier="g_drive_poll_for_media_finish" throws="1"> + <doc xml:space="preserve">Finishes an operation started with g_drive_poll_for_media() on a drive.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the drive has been poll_for_mediaed successfully, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="start" c:identifier="g_drive_start" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the start operation.</doc> + <type name="DriveStartFlags" c:type="GDriveStartFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="start_finish" c:identifier="g_drive_start_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes starting a drive.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the drive has been started successfully, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="stop" c:identifier="g_drive_stop" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for stopping.</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="stop_finish" c:identifier="g_drive_stop_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes stopping a drive.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the drive has been stopped successfully, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <glib:signal name="changed" when="last"> + <doc xml:space="preserve">Emitted when the drive's state has changed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + <glib:signal name="disconnected" when="last"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + <glib:signal name="eject-button" when="last"> + <doc xml:space="preserve">Emitted when the physical eject button (if any) of a drive has +been pressed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + <glib:signal name="stop-button" when="last" version="2.22"> + <doc xml:space="preserve">Emitted when the physical stop button (if any) of a drive has +been pressed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + </interface> + <record name="DriveIface" c:type="GDriveIface" glib:is-gtype-struct-for="Drive"> + <doc xml:space="preserve">Interface for creating #GDrive implementations.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="changed"> + <callback name="changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="disconnected"> + <callback name="disconnected"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject_button"> + <callback name="eject_button"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_name"> + <callback name="get_name"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a string containing @drive's name. The returned + string should be freed when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_icon"> + <callback name="get_icon"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GIcon for the @drive. + Free the returned object with g_object_unref().</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="has_volumes"> + <callback name="has_volumes"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive contains volumes, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_volumes"> + <callback name="get_volumes"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GList containing any #GVolume objects on the given @drive.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="Volume"/> + </type> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="is_media_removable"> + <callback name="is_media_removable"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @drive supports removable media, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="has_media"> + <callback name="has_media"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @drive has media, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="is_media_check_automatic"> + <callback name="is_media_check_automatic"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive is capable of automatically detecting + media changes, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_eject"> + <callback name="can_eject"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive can be ejected, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_poll_for_media"> + <callback name="can_poll_for_media"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive can be polled for media changes, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject"> + <callback name="eject"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject_finish"> + <callback name="eject_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the drive has been ejected successfully, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="poll_for_media"> + <callback name="poll_for_media"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="poll_for_media_finish"> + <callback name="poll_for_media_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the drive has been poll_for_mediaed successfully, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_identifier"> + <callback name="get_identifier"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly allocated string containing the + requested identifier, or %NULL if the #GDrive + doesn't have this kind of identifier.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + <parameter name="kind" transfer-ownership="none"> + <doc xml:space="preserve">the kind of identifier to return</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="enumerate_identifiers"> + <callback name="enumerate_identifiers"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated + array of strings containing kinds of identifiers. Use g_strfreev() + to free.</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_start_stop_type"> + <callback name="get_start_stop_type"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A value from the #GDriveStartStopType enumeration.</doc> + <type name="DriveStartStopType" c:type="GDriveStartStopType"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_start"> + <callback name="can_start"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive can be started, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_start_degraded"> + <callback name="can_start_degraded"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive can be started degraded, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="start"> + <callback name="start"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the start operation.</doc> + <type name="DriveStartFlags" c:type="GDriveStartFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="start_finish"> + <callback name="start_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the drive has been started successfully, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_stop"> + <callback name="can_stop"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @drive can be stopped, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="stop"> + <callback name="stop"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for stopping.</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="stop_finish"> + <callback name="stop_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the drive has been stopped successfully, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="stop_button"> + <callback name="stop_button"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject_with_operation"> + <callback name="eject_with_operation"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject_with_operation_finish"> + <callback name="eject_with_operation_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the drive was successfully ejected. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_sort_key"> + <callback name="get_sort_key"> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">Sorting key for @drive or %NULL if no such key is available.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">A #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_symbolic_icon"> + <callback name="get_symbolic_icon"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">symbolic #GIcon for the @drive. + Free the returned object with g_object_unref().</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="is_removable"> + <callback name="is_removable"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @drive and/or its media is considered removable, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive.</doc> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <bitfield name="DriveStartFlags" version="2.22" glib:type-name="GDriveStartFlags" glib:get-type="g_drive_start_flags_get_type" c:type="GDriveStartFlags"> + <doc xml:space="preserve">Flags used when starting a drive.</doc> + <member name="none" value="0" c:identifier="G_DRIVE_START_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + </bitfield> + <enumeration name="DriveStartStopType" version="2.22" glib:type-name="GDriveStartStopType" glib:get-type="g_drive_start_stop_type_get_type" c:type="GDriveStartStopType"> + <doc xml:space="preserve">Enumeration describing how a drive can be started/stopped.</doc> + <member name="unknown" value="0" c:identifier="G_DRIVE_START_STOP_TYPE_UNKNOWN" glib:nick="unknown"> + <doc xml:space="preserve">Unknown or drive doesn't support + start/stop.</doc> + </member> + <member name="shutdown" value="1" c:identifier="G_DRIVE_START_STOP_TYPE_SHUTDOWN" glib:nick="shutdown"> + <doc xml:space="preserve">The stop method will physically + shut down the drive and e.g. power down the port the drive is + attached to.</doc> + </member> + <member name="network" value="2" c:identifier="G_DRIVE_START_STOP_TYPE_NETWORK" glib:nick="network"> + <doc xml:space="preserve">The start/stop methods are used + for connecting/disconnect to the drive over the network.</doc> + </member> + <member name="multidisk" value="3" c:identifier="G_DRIVE_START_STOP_TYPE_MULTIDISK" glib:nick="multidisk"> + <doc xml:space="preserve">The start/stop methods will + assemble/disassemble a virtual drive from several physical + drives.</doc> + </member> + <member name="password" value="4" c:identifier="G_DRIVE_START_STOP_TYPE_PASSWORD" glib:nick="password"> + <doc xml:space="preserve">The start/stop methods will + unlock/lock the disk (for example using the ATA <quote>SECURITY + UNLOCK DEVICE</quote> command)</doc> + </member> + </enumeration> + <interface name="DtlsClientConnection" c:symbol-prefix="dtls_client_connection" c:type="GDtlsClientConnection" version="2.48" glib:type-name="GDtlsClientConnection" glib:get-type="g_dtls_client_connection_get_type" glib:type-struct="DtlsClientConnectionInterface"> + <doc xml:space="preserve">#GDtlsClientConnection is the client-side subclass of +#GDtlsConnection, representing a client-side DTLS connection.</doc> + <prerequisite name="DatagramBased"/> + <prerequisite name="DtlsConnection"/> + <function name="new" c:identifier="g_dtls_client_connection_new" version="2.48" throws="1"> + <doc xml:space="preserve">Creates a new #GDtlsClientConnection wrapping @base_socket which is +assumed to communicate with the server identified by @server_identity.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new + #GDtlsClientConnection, or %NULL on error</doc> + <type name="DtlsClientConnection" c:type="GDatagramBased*"/> + </return-value> + <parameters> + <parameter name="base_socket" transfer-ownership="none"> + <doc xml:space="preserve">the #GDatagramBased to wrap</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </parameter> + <parameter name="server_identity" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected identity of the server</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + </parameters> + </function> + <method name="get_accepted_cas" c:identifier="g_dtls_client_connection_get_accepted_cas" version="2.48"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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().</doc> + <type name="GLib.List" c:type="GList*"> + <array name="GLib.ByteArray"> + <type name="guint8" c:type="guint8"/> + </array> + </type> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">the #GDtlsClientConnection</doc> + <type name="DtlsClientConnection" c:type="GDtlsClientConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_server_identity" c:identifier="g_dtls_client_connection_get_server_identity" version="2.48"> + <doc xml:space="preserve">Gets @conn's expected server identity</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable describing the +expected server identity, or %NULL if the expected identity is not +known.</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">the #GDtlsClientConnection</doc> + <type name="DtlsClientConnection" c:type="GDtlsClientConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_validation_flags" c:identifier="g_dtls_client_connection_get_validation_flags" version="2.48"> + <doc xml:space="preserve">Gets @conn's validation flags</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the validation flags</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">the #GDtlsClientConnection</doc> + <type name="DtlsClientConnection" c:type="GDtlsClientConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_server_identity" c:identifier="g_dtls_client_connection_set_server_identity" version="2.48"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">the #GDtlsClientConnection</doc> + <type name="DtlsClientConnection" c:type="GDtlsClientConnection*"/> + </instance-parameter> + <parameter name="identity" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable describing the expected server identity</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + </parameters> + </method> + <method name="set_validation_flags" c:identifier="g_dtls_client_connection_set_validation_flags" version="2.48"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">the #GDtlsClientConnection</doc> + <type name="DtlsClientConnection" c:type="GDtlsClientConnection*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsCertificateFlags to use</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </parameter> + </parameters> + </method> + <property name="accepted-cas" version="2.48" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="GLib.List" c:type="gpointer"> + <type name="gpointer" c:type="gpointer"/> + </type> + </property> + <property name="server-identity" version="2.48" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="SocketConnectable"/> + </property> + <property name="validation-flags" version="2.48" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">What steps to perform when validating a certificate received from +a server. Server certificates that fail to validate in any of the +ways indicated here will be rejected unless the application +overrides the default via #GDtlsConnection::accept-certificate.</doc> + <type name="TlsCertificateFlags"/> + </property> + </interface> + <record name="DtlsClientConnectionInterface" c:type="GDtlsClientConnectionInterface" glib:is-gtype-struct-for="DtlsClientConnection" version="2.48"> + <doc xml:space="preserve">vtable for a #GDtlsClientConnection implementation.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + </record> + <interface name="DtlsConnection" c:symbol-prefix="dtls_connection" c:type="GDtlsConnection" version="2.48" glib:type-name="GDtlsConnection" glib:get-type="g_dtls_connection_get_type" glib:type-struct="DtlsConnectionInterface"> + <doc xml:space="preserve">#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.</doc> + <prerequisite name="DatagramBased"/> + <virtual-method name="accept_certificate"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="peer_cert" transfer-ownership="none"> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="errors" transfer-ownership="none"> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_binding_data" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="type" transfer-ownership="none"> + <type name="TlsChannelBindingType" c:type="GTlsChannelBindingType"/> + </parameter> + <parameter name="data" transfer-ownership="none"> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_negotiated_protocol" invoker="get_negotiated_protocol" version="2.60"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the negotiated protocol, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="handshake" invoker="handshake" version="2.48" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">success or failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="handshake_async" invoker="handshake_async" version="2.48"> + <doc xml:space="preserve">Asynchronously performs a TLS handshake on @conn. See +g_dtls_connection_handshake() for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call when the handshake is complete</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="handshake_finish" invoker="handshake_finish" version="2.48" throws="1"> + <doc xml:space="preserve">Finish an asynchronous TLS handshake operation. See +g_dtls_connection_handshake() for more information.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on failure, in which +case @error will be set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="set_advertised_protocols" invoker="set_advertised_protocols" version="2.60"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="protocols" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %NULL-terminated + array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL</doc> + <array c:type="const gchar* const*"> + <type name="utf8" c:type="gchar*"/> + </array> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="shutdown" invoker="shutdown" version="2.48" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="shutdown_read" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop reception of incoming datagrams</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="shutdown_write" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop sending outgoing datagrams</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="shutdown_async" invoker="shutdown_async" version="2.48"> + <doc xml:space="preserve">Asynchronously shut down part or all of the DTLS connection. See +g_dtls_connection_shutdown() for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="shutdown_read" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop reception of incoming datagrams</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="shutdown_write" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop sending outgoing datagrams</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the shutdown operation is complete</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="shutdown_finish" invoker="shutdown_finish" version="2.48" throws="1"> + <doc xml:space="preserve">Finish an asynchronous TLS shutdown operation. See +g_dtls_connection_shutdown() for more information.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on failure, in which +case @error will be set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <method name="close" c:identifier="g_dtls_connection_close" version="2.48" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="close_async" c:identifier="g_dtls_connection_close_async" version="2.48"> + <doc xml:space="preserve">Asynchronously close the DTLS connection. See g_dtls_connection_close() for +more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call when the close operation is complete</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="close_finish" c:identifier="g_dtls_connection_close_finish" version="2.48" throws="1"> + <doc xml:space="preserve">Finish an asynchronous TLS close operation. See g_dtls_connection_close() +for more information.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on failure, in which +case @error will be set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="emit_accept_certificate" c:identifier="g_dtls_connection_emit_accept_certificate" version="2.48"> + <doc xml:space="preserve">Used by #GDtlsConnection implementations to emit the +#GDtlsConnection::accept-certificate signal.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if one of the signal handlers has returned + %TRUE to accept @peer_cert</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="peer_cert" transfer-ownership="none"> + <doc xml:space="preserve">the peer's #GTlsCertificate</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="errors" transfer-ownership="none"> + <doc xml:space="preserve">the problems with @peer_cert</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </parameter> + </parameters> + </method> + <method name="get_certificate" c:identifier="g_dtls_connection_get_certificate" version="2.48"> + <doc xml:space="preserve">Gets @conn's certificate, as set by +g_dtls_connection_set_certificate().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">@conn's certificate, or %NULL</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_channel_binding_data" c:identifier="g_dtls_connection_get_channel_binding_data" version="2.66" throws="1"> + <doc xml:space="preserve">Query the TLS backend for TLS channel binding data of @type for @conn. + +This call retrieves TLS channel binding data as specified in RFC +[5056](https://tools.ietf.org/html/rfc5056), RFC +[5929](https://tools.ietf.org/html/rfc5929), and related RFCs. The +binding data is returned in @data. The @data is resized by the callee +using #GByteArray buffer management and will be freed when the @data +is destroyed by g_byte_array_unref(). If @data is %NULL, it will only +check whether TLS backend is able to fetch the data (e.g. whether @type +is supported by the TLS backend). It does not guarantee that the data +will be available though. That could happen if TLS connection does not +support @type or the binding data is not available yet due to additional +negotiation or input required.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">#GTlsChannelBindingType type of data to fetch</doc> + <type name="TlsChannelBindingType" c:type="GTlsChannelBindingType"/> + </parameter> + <parameter name="data" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">#GByteArray is + filled with the binding data, or %NULL</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + </parameters> + </method> + <method name="get_database" c:identifier="g_dtls_connection_get_database" version="2.48"> + <doc xml:space="preserve">Gets the certificate database that @conn uses to verify +peer certificates. See g_dtls_connection_set_database().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the certificate database that @conn uses or %NULL</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_interaction" c:identifier="g_dtls_connection_get_interaction" version="2.48"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The interaction object.</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a connection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_negotiated_protocol" c:identifier="g_dtls_connection_get_negotiated_protocol" version="2.60"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the negotiated protocol, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_peer_certificate" c:identifier="g_dtls_connection_get_peer_certificate" version="2.48"> + <doc xml:space="preserve">Gets @conn's peer's certificate after the handshake has completed +or failed. (It is not set during the emission of +#GDtlsConnection::accept-certificate.)</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">@conn's peer's certificate, or %NULL</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_peer_certificate_errors" c:identifier="g_dtls_connection_get_peer_certificate_errors" version="2.48"> + <doc xml:space="preserve">Gets the errors associated with validating @conn's peer's +certificate, after the handshake has completed or failed. (It is +not set during the emission of #GDtlsConnection::accept-certificate.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@conn's peer's certificate errors</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_rehandshake_mode" c:identifier="g_dtls_connection_get_rehandshake_mode" version="2.48" deprecated="1" deprecated-version="2.64."> + <doc xml:space="preserve">Gets @conn rehandshaking mode. See +g_dtls_connection_set_rehandshake_mode() for details.</doc> + <doc-deprecated xml:space="preserve">Changing the rehandshake mode is no longer + required for compatibility. Also, rehandshaking has been removed + from the TLS protocol in TLS 1.3.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%G_TLS_REHANDSHAKE_SAFELY</doc> + <type name="TlsRehandshakeMode" c:type="GTlsRehandshakeMode"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_require_close_notify" c:identifier="g_dtls_connection_get_require_close_notify" version="2.48"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @conn requires a proper TLS close notification.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="handshake" c:identifier="g_dtls_connection_handshake" version="2.48" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">success or failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="handshake_async" c:identifier="g_dtls_connection_handshake_async" version="2.48"> + <doc xml:space="preserve">Asynchronously performs a TLS handshake on @conn. See +g_dtls_connection_handshake() for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call when the handshake is complete</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="handshake_finish" c:identifier="g_dtls_connection_handshake_finish" version="2.48" throws="1"> + <doc xml:space="preserve">Finish an asynchronous TLS handshake operation. See +g_dtls_connection_handshake() for more information.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on failure, in which +case @error will be set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="set_advertised_protocols" c:identifier="g_dtls_connection_set_advertised_protocols" version="2.60"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="protocols" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %NULL-terminated + array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL</doc> + <array c:type="const gchar* const*"> + <type name="utf8" c:type="gchar*"/> + </array> + </parameter> + </parameters> + </method> + <method name="set_certificate" c:identifier="g_dtls_connection_set_certificate" version="2.48"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="certificate" transfer-ownership="none"> + <doc xml:space="preserve">the certificate to use for @conn</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + </parameters> + </method> + <method name="set_database" c:identifier="g_dtls_connection_set_database" version="2.48"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="database" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </parameter> + </parameters> + </method> + <method name="set_interaction" c:identifier="g_dtls_connection_set_interaction" version="2.48"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a connection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an interaction object, or %NULL</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + </parameters> + </method> + <method name="set_rehandshake_mode" c:identifier="g_dtls_connection_set_rehandshake_mode" version="2.48" deprecated="1" deprecated-version="2.60."> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Changing the rehandshake mode is no longer + required for compatibility. Also, rehandshaking has been removed + from the TLS protocol in TLS 1.3.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve">the rehandshaking mode</doc> + <type name="TlsRehandshakeMode" c:type="GTlsRehandshakeMode"/> + </parameter> + </parameters> + </method> + <method name="set_require_close_notify" c:identifier="g_dtls_connection_set_require_close_notify" version="2.48"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="require_close_notify" transfer-ownership="none"> + <doc xml:space="preserve">whether or not to require close notification</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="shutdown" c:identifier="g_dtls_connection_shutdown" version="2.48" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="shutdown_read" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop reception of incoming datagrams</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="shutdown_write" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop sending outgoing datagrams</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="shutdown_async" c:identifier="g_dtls_connection_shutdown_async" version="2.48"> + <doc xml:space="preserve">Asynchronously shut down part or all of the DTLS connection. See +g_dtls_connection_shutdown() for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="shutdown_read" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop reception of incoming datagrams</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="shutdown_write" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop sending outgoing datagrams</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the shutdown operation is complete</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="shutdown_finish" c:identifier="g_dtls_connection_shutdown_finish" version="2.48" throws="1"> + <doc xml:space="preserve">Finish an asynchronous TLS shutdown operation. See +g_dtls_connection_shutdown() for more information.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on failure, in which +case @error will be set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <property name="advertised-protocols" version="2.60" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">The list of application-layer protocols that the connection +advertises that it is willing to speak. See +g_dtls_connection_set_advertised_protocols().</doc> + <array> + <type name="utf8"/> + </array> + </property> + <property name="base-socket" version="2.48" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The #GDatagramBased that the connection wraps. Note that this may be any +implementation of #GDatagramBased, not just a #GSocket.</doc> + <type name="DatagramBased"/> + </property> + <property name="certificate" version="2.48" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">The connection's certificate; see +g_dtls_connection_set_certificate().</doc> + <type name="TlsCertificate"/> + </property> + <property name="database" version="2.48" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">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().</doc> + <type name="TlsDatabase"/> + </property> + <property name="interaction" version="2.48" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="TlsInteraction"/> + </property> + <property name="negotiated-protocol" version="2.60" transfer-ownership="none"> + <doc xml:space="preserve">The application-layer protocol negotiated during the TLS +handshake. See g_dtls_connection_get_negotiated_protocol().</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="peer-certificate" version="2.48" transfer-ownership="none"> + <doc xml:space="preserve">The connection's peer's certificate, after the TLS handshake has +completed or failed. 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.)</doc> + <type name="TlsCertificate"/> + </property> + <property name="peer-certificate-errors" version="2.48" transfer-ownership="none"> + <doc xml:space="preserve">The errors noticed 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.</doc> + <type name="TlsCertificateFlags"/> + </property> + <property name="rehandshake-mode" version="2.48" deprecated="1" deprecated-version="2.60" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">The rehandshaking mode. See +g_dtls_connection_set_rehandshake_mode().</doc> + <doc-deprecated xml:space="preserve">The rehandshake mode is ignored.</doc-deprecated> + <type name="TlsRehandshakeMode"/> + </property> + <property name="require-close-notify" version="2.48" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">Whether or not proper TLS close notification is required. +See g_dtls_connection_set_require_close_notify().</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <glib:signal name="accept-certificate" when="last" version="2.48"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%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.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="peer_cert" transfer-ownership="none"> + <doc xml:space="preserve">the peer's #GTlsCertificate</doc> + <type name="TlsCertificate"/> + </parameter> + <parameter name="errors" transfer-ownership="none"> + <doc xml:space="preserve">the problems with @peer_cert.</doc> + <type name="TlsCertificateFlags"/> + </parameter> + </parameters> + </glib:signal> + </interface> + <record name="DtlsConnectionInterface" c:type="GDtlsConnectionInterface" glib:is-gtype-struct-for="DtlsConnection" version="2.48"> + <doc xml:space="preserve">Virtual method table for a #GDtlsConnection implementation.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="accept_certificate"> + <callback name="accept_certificate"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </parameter> + <parameter name="peer_cert" transfer-ownership="none"> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="errors" transfer-ownership="none"> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </parameter> + </parameters> + </callback> + </field> + <field name="handshake"> + <callback name="handshake" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">success or failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="handshake_async"> + <callback name="handshake_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call when the handshake is complete</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="handshake_finish"> + <callback name="handshake_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on failure, in which +case @error will be set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="shutdown"> + <callback name="shutdown" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </parameter> + <parameter name="shutdown_read" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop reception of incoming datagrams</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="shutdown_write" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop sending outgoing datagrams</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="shutdown_async"> + <callback name="shutdown_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </parameter> + <parameter name="shutdown_read" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop reception of incoming datagrams</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="shutdown_write" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop sending outgoing datagrams</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">callback to call when the shutdown operation is complete</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="shutdown_finish"> + <callback name="shutdown_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on failure, in which +case @error will be set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="set_advertised_protocols"> + <callback name="set_advertised_protocols"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </parameter> + <parameter name="protocols" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %NULL-terminated + array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL</doc> + <array c:type="const gchar* const*"> + <type name="utf8" c:type="gchar*"/> + </array> + </parameter> + </parameters> + </callback> + </field> + <field name="get_negotiated_protocol"> + <callback name="get_negotiated_protocol"> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the negotiated protocol, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GDtlsConnection</doc> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_binding_data"> + <callback name="get_binding_data" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="conn" transfer-ownership="none"> + <type name="DtlsConnection" c:type="GDtlsConnection*"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <type name="TlsChannelBindingType" c:type="GTlsChannelBindingType"/> + </parameter> + <parameter name="data" transfer-ownership="none"> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + </parameters> + </callback> + </field> + </record> + <interface name="DtlsServerConnection" c:symbol-prefix="dtls_server_connection" c:type="GDtlsServerConnection" version="2.48" glib:type-name="GDtlsServerConnection" glib:get-type="g_dtls_server_connection_get_type" glib:type-struct="DtlsServerConnectionInterface"> + <doc xml:space="preserve">#GDtlsServerConnection is the server-side subclass of #GDtlsConnection, +representing a server-side DTLS connection.</doc> + <prerequisite name="DatagramBased"/> + <prerequisite name="DtlsConnection"/> + <function name="new" c:identifier="g_dtls_server_connection_new" version="2.48" throws="1"> + <doc xml:space="preserve">Creates a new #GDtlsServerConnection wrapping @base_socket.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new + #GDtlsServerConnection, or %NULL on error</doc> + <type name="DtlsServerConnection" c:type="GDatagramBased*"/> + </return-value> + <parameters> + <parameter name="base_socket" transfer-ownership="none"> + <doc xml:space="preserve">the #GDatagramBased to wrap</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </parameter> + <parameter name="certificate" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the default server certificate, or %NULL</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + </parameters> + </function> + <property name="authentication-mode" version="2.48" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="TlsAuthenticationMode"/> + </property> + </interface> + <record name="DtlsServerConnectionInterface" c:type="GDtlsServerConnectionInterface" glib:is-gtype-struct-for="DtlsServerConnection" version="2.48"> + <doc xml:space="preserve">vtable for a #GDtlsServerConnection implementation.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + </record> + <function-macro name="EMBLEM" c:identifier="G_EMBLEM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="EMBLEMED_ICON" c:identifier="G_EMBLEMED_ICON" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="EMBLEMED_ICON_CLASS" c:identifier="G_EMBLEMED_ICON_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="EMBLEMED_ICON_GET_CLASS" c:identifier="G_EMBLEMED_ICON_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="EMBLEM_CLASS" c:identifier="G_EMBLEM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="EMBLEM_GET_CLASS" c:identifier="G_EMBLEM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <class name="Emblem" c:symbol-prefix="emblem" c:type="GEmblem" parent="GObject.Object" glib:type-name="GEmblem" glib:get-type="g_emblem_get_type" glib:type-struct="EmblemClass"> + <doc xml:space="preserve">#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.</doc> + <implements name="Icon"/> + <constructor name="new" c:identifier="g_emblem_new" version="2.18"> + <doc xml:space="preserve">Creates a new emblem for @icon.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GEmblem.</doc> + <type name="Emblem" c:type="GEmblem*"/> + </return-value> + <parameters> + <parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a GIcon containing the icon.</doc> + <type name="Icon" c:type="GIcon*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_with_origin" c:identifier="g_emblem_new_with_origin" version="2.18"> + <doc xml:space="preserve">Creates a new emblem for @icon.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GEmblem.</doc> + <type name="Emblem" c:type="GEmblem*"/> + </return-value> + <parameters> + <parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a GIcon containing the icon.</doc> + <type name="Icon" c:type="GIcon*"/> + </parameter> + <parameter name="origin" transfer-ownership="none"> + <doc xml:space="preserve">a GEmblemOrigin enum defining the emblem's origin</doc> + <type name="EmblemOrigin" c:type="GEmblemOrigin"/> + </parameter> + </parameters> + </constructor> + <method name="get_icon" c:identifier="g_emblem_get_icon" version="2.18"> + <doc xml:space="preserve">Gives back the icon from @emblem.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GIcon. The returned object belongs to + the emblem and should not be modified or freed.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="emblem" transfer-ownership="none"> + <doc xml:space="preserve">a #GEmblem from which the icon should be extracted.</doc> + <type name="Emblem" c:type="GEmblem*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_origin" c:identifier="g_emblem_get_origin" version="2.18"> + <doc xml:space="preserve">Gets the origin of the emblem.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the origin of the emblem</doc> + <type name="EmblemOrigin" c:type="GEmblemOrigin"/> + </return-value> + <parameters> + <instance-parameter name="emblem" transfer-ownership="none"> + <doc xml:space="preserve">a #GEmblem</doc> + <type name="Emblem" c:type="GEmblem*"/> + </instance-parameter> + </parameters> + </method> + <property name="icon" writable="1" construct-only="1" transfer-ownership="none"> + <type name="GObject.Object"/> + </property> + <property name="origin" writable="1" construct-only="1" transfer-ownership="none"> + <type name="EmblemOrigin"/> + </property> + </class> + <record name="EmblemClass" c:type="GEmblemClass" disguised="1" glib:is-gtype-struct-for="Emblem"/> + <enumeration name="EmblemOrigin" version="2.18" glib:type-name="GEmblemOrigin" glib:get-type="g_emblem_origin_get_type" c:type="GEmblemOrigin"> + <doc xml:space="preserve">GEmblemOrigin is used to add information about the origin of the emblem +to #GEmblem.</doc> + <member name="unknown" value="0" c:identifier="G_EMBLEM_ORIGIN_UNKNOWN" glib:nick="unknown"> + <doc xml:space="preserve">Emblem of unknown origin</doc> + </member> + <member name="device" value="1" c:identifier="G_EMBLEM_ORIGIN_DEVICE" glib:nick="device"> + <doc xml:space="preserve">Emblem adds device-specific information</doc> + </member> + <member name="livemetadata" value="2" c:identifier="G_EMBLEM_ORIGIN_LIVEMETADATA" glib:nick="livemetadata"> + <doc xml:space="preserve">Emblem depicts live metadata, such as "readonly"</doc> + </member> + <member name="tag" value="3" c:identifier="G_EMBLEM_ORIGIN_TAG" glib:nick="tag"> + <doc xml:space="preserve">Emblem comes from a user-defined tag, e.g. set by nautilus (in the future)</doc> + </member> + </enumeration> + <class name="EmblemedIcon" c:symbol-prefix="emblemed_icon" c:type="GEmblemedIcon" parent="GObject.Object" glib:type-name="GEmblemedIcon" glib:get-type="g_emblemed_icon_get_type" glib:type-struct="EmblemedIconClass"> + <doc xml:space="preserve">#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.</doc> + <implements name="Icon"/> + <constructor name="new" c:identifier="g_emblemed_icon_new" version="2.18"> + <doc xml:space="preserve">Creates a new emblemed icon for @icon with the emblem @emblem.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GIcon</doc> + <type name="EmblemedIcon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GIcon</doc> + <type name="Icon" c:type="GIcon*"/> + </parameter> + <parameter name="emblem" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GEmblem, or %NULL</doc> + <type name="Emblem" c:type="GEmblem*"/> + </parameter> + </parameters> + </constructor> + <method name="add_emblem" c:identifier="g_emblemed_icon_add_emblem" version="2.18"> + <doc xml:space="preserve">Adds @emblem to the #GList of #GEmblems.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="emblemed" transfer-ownership="none"> + <doc xml:space="preserve">a #GEmblemedIcon</doc> + <type name="EmblemedIcon" c:type="GEmblemedIcon*"/> + </instance-parameter> + <parameter name="emblem" transfer-ownership="none"> + <doc xml:space="preserve">a #GEmblem</doc> + <type name="Emblem" c:type="GEmblem*"/> + </parameter> + </parameters> + </method> + <method name="clear_emblems" c:identifier="g_emblemed_icon_clear_emblems" version="2.28"> + <doc xml:space="preserve">Removes all the emblems from @icon.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="emblemed" transfer-ownership="none"> + <doc xml:space="preserve">a #GEmblemedIcon</doc> + <type name="EmblemedIcon" c:type="GEmblemedIcon*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_emblems" c:identifier="g_emblemed_icon_get_emblems" version="2.18"> + <doc xml:space="preserve">Gets the list of emblems for the @icon.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GList of + #GEmblems that is owned by @emblemed</doc> + <type name="GLib.List" c:type="GList*"> + <type name="Emblem"/> + </type> + </return-value> + <parameters> + <instance-parameter name="emblemed" transfer-ownership="none"> + <doc xml:space="preserve">a #GEmblemedIcon</doc> + <type name="EmblemedIcon" c:type="GEmblemedIcon*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_icon" c:identifier="g_emblemed_icon_get_icon" version="2.18"> + <doc xml:space="preserve">Gets the main icon for @emblemed.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GIcon that is owned by @emblemed</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="emblemed" transfer-ownership="none"> + <doc xml:space="preserve">a #GEmblemedIcon</doc> + <type name="EmblemedIcon" c:type="GEmblemedIcon*"/> + </instance-parameter> + </parameters> + </method> + <property name="gicon" writable="1" construct-only="1" transfer-ownership="none"> + <type name="Icon"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="EmblemedIconPrivate" c:type="GEmblemedIconPrivate*"/> + </field> + </class> + <record name="EmblemedIconClass" c:type="GEmblemedIconClass" glib:is-gtype-struct-for="EmblemedIcon"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <record name="EmblemedIconPrivate" c:type="GEmblemedIconPrivate" disguised="1"/> + <function-macro name="FILE" c:identifier="G_FILE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILENAME_COMPLETER" c:identifier="G_FILENAME_COMPLETER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILENAME_COMPLETER_CLASS" c:identifier="G_FILENAME_COMPLETER_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILENAME_COMPLETER_GET_CLASS" c:identifier="G_FILENAME_COMPLETER_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <constant name="FILE_ATTRIBUTE_ACCESS_CAN_DELETE" value="access::can-delete" c:type="G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE" value="access::can-execute" c:type="G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_ACCESS_CAN_READ" value="access::can-read" c:type="G_FILE_ATTRIBUTE_ACCESS_CAN_READ"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_ACCESS_CAN_RENAME" value="access::can-rename" c:type="G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_ACCESS_CAN_TRASH" value="access::can-trash" c:type="G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_ACCESS_CAN_WRITE" value="access::can-write" c:type="G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_DOS_IS_ARCHIVE" value="dos::is-archive" c:type="G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_DOS_IS_MOUNTPOINT" value="dos::is-mountpoint" c:type="G_FILE_ATTRIBUTE_DOS_IS_MOUNTPOINT" version="2.60"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_DOS_IS_SYSTEM" value="dos::is-system" c:type="G_FILE_ATTRIBUTE_DOS_IS_SYSTEM"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_DOS_REPARSE_POINT_TAG" value="dos::reparse-point-tag" c:type="G_FILE_ATTRIBUTE_DOS_REPARSE_POINT_TAG" version="2.60"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_ETAG_VALUE" value="etag::value" c:type="G_FILE_ATTRIBUTE_ETAG_VALUE"> + <doc xml:space="preserve">A key in the "etag" namespace for getting the value of the file's +entity tag. Corresponding #GFileAttributeType is +%G_FILE_ATTRIBUTE_TYPE_STRING.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_FILESYSTEM_FREE" value="filesystem::free" c:type="G_FILE_ATTRIBUTE_FILESYSTEM_FREE"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_FILESYSTEM_READONLY" value="filesystem::readonly" c:type="G_FILE_ATTRIBUTE_FILESYSTEM_READONLY"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_FILESYSTEM_REMOTE" value="filesystem::remote" c:type="G_FILE_ATTRIBUTE_FILESYSTEM_REMOTE"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_FILESYSTEM_SIZE" value="filesystem::size" c:type="G_FILE_ATTRIBUTE_FILESYSTEM_SIZE"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_FILESYSTEM_TYPE" value="filesystem::type" c:type="G_FILE_ATTRIBUTE_FILESYSTEM_TYPE"> + <doc xml:space="preserve">A key in the "filesystem" namespace for getting the file system's type. +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_FILESYSTEM_USED" value="filesystem::used" c:type="G_FILE_ATTRIBUTE_FILESYSTEM_USED" version="2.32"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW" value="filesystem::use-preview" c:type="G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_GVFS_BACKEND" value="gvfs::backend" c:type="G_FILE_ATTRIBUTE_GVFS_BACKEND"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_ID_FILE" value="id::file" c:type="G_FILE_ATTRIBUTE_ID_FILE"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_ID_FILESYSTEM" value="id::filesystem" c:type="G_FILE_ATTRIBUTE_ID_FILESYSTEM"> + <doc xml:space="preserve">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).</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT" value="mountable::can-eject" c:type="G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT" value="mountable::can-mount" c:type="G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_MOUNTABLE_CAN_POLL" value="mountable::can-poll" c:type="G_FILE_ATTRIBUTE_MOUNTABLE_CAN_POLL" version="2.22"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_MOUNTABLE_CAN_START" value="mountable::can-start" c:type="G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START" version="2.22"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_MOUNTABLE_CAN_START_DEGRADED" value="mountable::can-start-degraded" c:type="G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START_DEGRADED" version="2.22"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_MOUNTABLE_CAN_STOP" value="mountable::can-stop" c:type="G_FILE_ATTRIBUTE_MOUNTABLE_CAN_STOP" version="2.22"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT" value="mountable::can-unmount" c:type="G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI" value="mountable::hal-udi" c:type="G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI"> + <doc xml:space="preserve">A key in the "mountable" namespace for getting the HAL UDI for the mountable +file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_MOUNTABLE_IS_MEDIA_CHECK_AUTOMATIC" value="mountable::is-media-check-automatic" c:type="G_FILE_ATTRIBUTE_MOUNTABLE_IS_MEDIA_CHECK_AUTOMATIC" version="2.22"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_MOUNTABLE_START_STOP_TYPE" value="mountable::start-stop-type" c:type="G_FILE_ATTRIBUTE_MOUNTABLE_START_STOP_TYPE" version="2.22"> + <doc xml:space="preserve">A key in the "mountable" namespace for getting the #GDriveStartStopType. +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE" value="mountable::unix-device" c:type="G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE"> + <doc xml:space="preserve">A key in the "mountable" namespace for getting the unix device. +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE" value="mountable::unix-device-file" c:type="G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE" version="2.22"> + <doc xml:space="preserve">A key in the "mountable" namespace for getting the unix device file. +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_OWNER_GROUP" value="owner::group" c:type="G_FILE_ATTRIBUTE_OWNER_GROUP"> + <doc xml:space="preserve">A key in the "owner" namespace for getting the file owner's group. +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_OWNER_USER" value="owner::user" c:type="G_FILE_ATTRIBUTE_OWNER_USER"> + <doc xml:space="preserve">A key in the "owner" namespace for getting the user name of the +file's owner. Corresponding #GFileAttributeType is +%G_FILE_ATTRIBUTE_TYPE_STRING.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_OWNER_USER_REAL" value="owner::user-real" c:type="G_FILE_ATTRIBUTE_OWNER_USER_REAL"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_PREVIEW_ICON" value="preview::icon" c:type="G_FILE_ATTRIBUTE_PREVIEW_ICON" version="2.20"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_RECENT_MODIFIED" value="recent::modified" c:type="G_FILE_ATTRIBUTE_RECENT_MODIFIED" version="2.52"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_SELINUX_CONTEXT" value="selinux::context" c:type="G_FILE_ATTRIBUTE_SELINUX_CONTEXT"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE" value="standard::allocated-size" c:type="G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE" version="2.20"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE" value="standard::content-type" c:type="G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_COPY_NAME" value="standard::copy-name" c:type="G_FILE_ATTRIBUTE_STANDARD_COPY_NAME"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_DESCRIPTION" value="standard::description" c:type="G_FILE_ATTRIBUTE_STANDARD_DESCRIPTION"> + <doc xml:space="preserve">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 further 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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME" value="standard::display-name" c:type="G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME"> + <doc xml:space="preserve">A key in the "standard" namespace for getting the display name of the file. +A display name is guaranteed to be in UTF-8 and can thus be displayed in +the UI. It is guaranteed to be set on every file. +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_EDIT_NAME" value="standard::edit-name" c:type="G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE" value="standard::fast-content-type" c:type="G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_ICON" value="standard::icon" c:type="G_FILE_ATTRIBUTE_STANDARD_ICON"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_IS_BACKUP" value="standard::is-backup" c:type="G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP"> + <doc xml:space="preserve">A key in the "standard" namespace for checking if a file is a backup file. +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_IS_HIDDEN" value="standard::is-hidden" c:type="G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN"> + <doc xml:space="preserve">A key in the "standard" namespace for checking if a file is hidden. +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_IS_SYMLINK" value="standard::is-symlink" c:type="G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL" value="standard::is-virtual" c:type="G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL"> + <doc xml:space="preserve">A key in the "standard" namespace for checking if a file is virtual. +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_IS_VOLATILE" value="standard::is-volatile" c:type="G_FILE_ATTRIBUTE_STANDARD_IS_VOLATILE" version="2.46"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_NAME" value="standard::name" c:type="G_FILE_ATTRIBUTE_STANDARD_NAME"> + <doc xml:space="preserve">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. It is guaranteed to be set on +every file. +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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_SIZE" value="standard::size" c:type="G_FILE_ATTRIBUTE_STANDARD_SIZE"> + <doc xml:space="preserve">A key in the "standard" namespace for getting the file's size (in bytes). +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_SORT_ORDER" value="standard::sort-order" c:type="G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON" value="standard::symbolic-icon" c:type="G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON" version="2.34"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET" value="standard::symlink-target" c:type="G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_TARGET_URI" value="standard::target-uri" c:type="G_FILE_ATTRIBUTE_STANDARD_TARGET_URI"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_STANDARD_TYPE" value="standard::type" c:type="G_FILE_ATTRIBUTE_STANDARD_TYPE"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_THUMBNAILING_FAILED" value="thumbnail::failed" c:type="G_FILE_ATTRIBUTE_THUMBNAILING_FAILED"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_THUMBNAIL_IS_VALID" value="thumbnail::is-valid" c:type="G_FILE_ATTRIBUTE_THUMBNAIL_IS_VALID" version="2.40"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_THUMBNAIL_PATH" value="thumbnail::path" c:type="G_FILE_ATTRIBUTE_THUMBNAIL_PATH"> + <doc xml:space="preserve">A key in the "thumbnail" namespace for getting the path to the thumbnail +image. Corresponding #GFileAttributeType is +%G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_TIME_ACCESS" value="time::access" c:type="G_FILE_ATTRIBUTE_TIME_ACCESS"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_TIME_ACCESS_USEC" value="time::access-usec" c:type="G_FILE_ATTRIBUTE_TIME_ACCESS_USEC"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_TIME_CHANGED" value="time::changed" c:type="G_FILE_ATTRIBUTE_TIME_CHANGED"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_TIME_CHANGED_USEC" value="time::changed-usec" c:type="G_FILE_ATTRIBUTE_TIME_CHANGED_USEC"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_TIME_CREATED" value="time::created" c:type="G_FILE_ATTRIBUTE_TIME_CREATED"> + <doc xml:space="preserve">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 may correspond to Linux stx_btime, FreeBSD st_birthtim, NetBSD +st_birthtime or NTFS ctime.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_TIME_CREATED_USEC" value="time::created-usec" c:type="G_FILE_ATTRIBUTE_TIME_CREATED_USEC"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_TIME_MODIFIED" value="time::modified" c:type="G_FILE_ATTRIBUTE_TIME_MODIFIED"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_TIME_MODIFIED_USEC" value="time::modified-usec" c:type="G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_TRASH_DELETION_DATE" value="trash::deletion-date" c:type="G_FILE_ATTRIBUTE_TRASH_DELETION_DATE" version="2.24"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_TRASH_ITEM_COUNT" value="trash::item-count" c:type="G_FILE_ATTRIBUTE_TRASH_ITEM_COUNT"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_TRASH_ORIG_PATH" value="trash::orig-path" c:type="G_FILE_ATTRIBUTE_TRASH_ORIG_PATH" version="2.24"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_UNIX_BLOCKS" value="unix::blocks" c:type="G_FILE_ATTRIBUTE_UNIX_BLOCKS"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_UNIX_BLOCK_SIZE" value="unix::block-size" c:type="G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_UNIX_DEVICE" value="unix::device" c:type="G_FILE_ATTRIBUTE_UNIX_DEVICE"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_UNIX_GID" value="unix::gid" c:type="G_FILE_ATTRIBUTE_UNIX_GID"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_UNIX_INODE" value="unix::inode" c:type="G_FILE_ATTRIBUTE_UNIX_INODE"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT" value="unix::is-mountpoint" c:type="G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_UNIX_MODE" value="unix::mode" c:type="G_FILE_ATTRIBUTE_UNIX_MODE"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_UNIX_NLINK" value="unix::nlink" c:type="G_FILE_ATTRIBUTE_UNIX_NLINK"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_UNIX_RDEV" value="unix::rdev" c:type="G_FILE_ATTRIBUTE_UNIX_RDEV"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="FILE_ATTRIBUTE_UNIX_UID" value="unix::uid" c:type="G_FILE_ATTRIBUTE_UNIX_UID"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="FILE_DESCRIPTOR_BASED" c:identifier="G_FILE_DESCRIPTOR_BASED" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_DESCRIPTOR_BASED_GET_IFACE" c:identifier="G_FILE_DESCRIPTOR_BASED_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_ENUMERATOR" c:identifier="G_FILE_ENUMERATOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_ENUMERATOR_CLASS" c:identifier="G_FILE_ENUMERATOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_ENUMERATOR_GET_CLASS" c:identifier="G_FILE_ENUMERATOR_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_GET_IFACE" c:identifier="G_FILE_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_ICON" c:identifier="G_FILE_ICON" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_ICON_CLASS" c:identifier="G_FILE_ICON_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_ICON_GET_CLASS" c:identifier="G_FILE_ICON_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_INFO" c:identifier="G_FILE_INFO" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_INFO_CLASS" c:identifier="G_FILE_INFO_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_INFO_GET_CLASS" c:identifier="G_FILE_INFO_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_INPUT_STREAM" c:identifier="G_FILE_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_INPUT_STREAM_CLASS" c:identifier="G_FILE_INPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_INPUT_STREAM_GET_CLASS" c:identifier="G_FILE_INPUT_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_IO_STREAM" c:identifier="G_FILE_IO_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_IO_STREAM_CLASS" c:identifier="G_FILE_IO_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_IO_STREAM_GET_CLASS" c:identifier="G_FILE_IO_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_MONITOR" c:identifier="G_FILE_MONITOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_MONITOR_CLASS" c:identifier="G_FILE_MONITOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_MONITOR_GET_CLASS" c:identifier="G_FILE_MONITOR_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_OUTPUT_STREAM" c:identifier="G_FILE_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_OUTPUT_STREAM_CLASS" c:identifier="G_FILE_OUTPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILE_OUTPUT_STREAM_GET_CLASS" c:identifier="G_FILE_OUTPUT_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILTER_INPUT_STREAM" c:identifier="G_FILTER_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILTER_INPUT_STREAM_CLASS" c:identifier="G_FILTER_INPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILTER_INPUT_STREAM_GET_CLASS" c:identifier="G_FILTER_INPUT_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILTER_OUTPUT_STREAM" c:identifier="G_FILTER_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILTER_OUTPUT_STREAM_CLASS" c:identifier="G_FILTER_OUTPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="FILTER_OUTPUT_STREAM_GET_CLASS" c:identifier="G_FILTER_OUTPUT_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <interface name="File" c:symbol-prefix="file" c:type="GFile" glib:type-name="GFile" glib:get-type="g_file_get_type" glib:type-struct="FileIface"> + <doc xml:space="preserve">#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.</doc> + <function name="new_build_filename" c:identifier="g_file_new_build_filename" version="2.56" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="first_element" transfer-ownership="none"> + <doc xml:space="preserve">the first element in the path</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">remaining elements in path, terminated by %NULL</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="new_for_commandline_arg" c:identifier="g_file_new_for_commandline_arg"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="arg" transfer-ownership="none"> + <doc xml:space="preserve">a command line string</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="new_for_commandline_arg_and_cwd" c:identifier="g_file_new_for_commandline_arg_and_cwd" version="2.36"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="arg" transfer-ownership="none"> + <doc xml:space="preserve">a command line string</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="cwd" transfer-ownership="none"> + <doc xml:space="preserve">the current working directory of the commandline</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="new_for_path" c:identifier="g_file_new_for_path"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile for the given @path. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a relative or absolute path. + The string must be encoded in the glib filename encoding.</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="new_for_uri" c:identifier="g_file_new_for_uri"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile for the given @uri. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 string containing a URI</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="new_tmp" c:identifier="g_file_new_tmp" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="tmpl" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Template for the file + name, as in g_file_open_tmp(), or %NULL for a default template</doc> + <type name="filename" c:type="const char*"/> + </parameter> + <parameter name="iostream" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">on return, a #GFileIOStream for the created file</doc> + <type name="FileIOStream" c:type="GFileIOStream**"/> + </parameter> + </parameters> + </function> + <function name="parse_name" c:identifier="g_file_parse_name"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="parse_name" transfer-ownership="none"> + <doc xml:space="preserve">a file name or path to be parsed</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <virtual-method name="append_to" invoker="append_to" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileOutputStream, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="append_to_async" invoker="append_to_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="append_to_finish" invoker="append_to_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file append operation started with +g_file_append_to_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a valid #GFileOutputStream + or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">#GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="copy" invoker="copy" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="destination" transfer-ownership="none"> + <doc xml:space="preserve">destination #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">set of #GFileCopyFlags</doc> + <type name="FileCopyFlags" c:type="GFileCopyFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="progress_callback" transfer-ownership="none" nullable="1" allow-none="1" scope="call" closure="4"> + <doc xml:space="preserve">function to callback with + progress information, or %NULL if progress information is not needed</doc> + <type name="FileProgressCallback" c:type="GFileProgressCallback"/> + </parameter> + <parameter name="progress_callback_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to @progress_callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="copy_async" invoker="copy_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="destination" transfer-ownership="none"> + <doc xml:space="preserve">destination #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">set of #GFileCopyFlags</doc> + <type name="FileCopyFlags" c:type="GFileCopyFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="progress_callback" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="5"> + <doc xml:space="preserve">function to callback with progress + information, or %NULL if progress information is not needed</doc> + <type name="FileProgressCallback" c:type="GFileProgressCallback"/> + </parameter> + <parameter name="progress_callback_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data to pass to @progress_callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="7"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="copy_finish" invoker="copy_finish" throws="1"> + <doc xml:space="preserve">Finishes copying the file started with g_file_copy_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a %TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="create" invoker="create" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileOutputStream for the newly created + file, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="create_async" invoker="create_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="create_finish" invoker="create_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file create operation started with +g_file_create_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileOutputStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="create_readwrite" invoker="create_readwrite" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileIOStream for the newly created + file, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="create_readwrite_async" invoker="create_readwrite_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="create_readwrite_finish" invoker="create_readwrite_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file create operation started with +g_file_create_readwrite_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileIOStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="delete_file" invoker="delete" throws="1"> + <doc xml:space="preserve">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 @file doesn’t exist, %G_IO_ERROR_NOT_FOUND will be returned. This allows +for deletion to be implemented avoiding +[time-of-check to time-of-use races](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use): +|[ +g_autoptr(GError) local_error = NULL; +if (!g_file_delete (my_file, my_cancellable, &local_error) && + !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND)) + { + // deletion failed for some reason other than the file not existing: + // so report the error + g_warning ("Failed to delete %s: %s", + g_file_peek_path (my_file), local_error->message); + } +]| + +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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the file was deleted. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="delete_file_async" invoker="delete_async" version="2.34"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="delete_file_finish" invoker="delete_finish" version="2.34" throws="1"> + <doc xml:space="preserve">Finishes deleting a file started with g_file_delete_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the file was deleted. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="dup" invoker="dup"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile that is a duplicate + of the given #GFile.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="eject_mountable" invoker="eject_mountable" deprecated="1" deprecated-version="2.22"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_file_eject_mountable_with_operation() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="eject_mountable_finish" invoker="eject_mountable_finish" deprecated="1" deprecated-version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous eject operation started by +g_file_eject_mountable().</doc> + <doc-deprecated xml:space="preserve">Use g_file_eject_mountable_with_operation_finish() + instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @file was ejected successfully. + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="eject_mountable_with_operation" invoker="eject_mountable_with_operation" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation, + or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="eject_mountable_with_operation_finish" invoker="eject_mountable_with_operation_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous eject operation started by +g_file_eject_mountable_with_operation().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @file was ejected successfully. + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="enumerate_children" invoker="enumerate_children" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GFileEnumerator if successful, + %NULL on error. Free the returned object with g_object_unref().</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="enumerate_children_async" invoker="enumerate_children_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the + request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="enumerate_children_finish" invoker="enumerate_children_finish" throws="1"> + <doc xml:space="preserve">Finishes an async enumerate children operation. +See g_file_enumerate_children_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileEnumerator or %NULL + if an error occurred. + Free the returned object with g_object_unref().</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="equal" invoker="equal"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @file1 and @file2 are equal.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file1" transfer-ownership="none"> + <doc xml:space="preserve">the first #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="file2" transfer-ownership="none"> + <doc xml:space="preserve">the second #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="find_enclosing_mount" invoker="find_enclosing_mount" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GMount where the @file is located + or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="Mount" c:type="GMount*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="find_enclosing_mount_async" invoker="find_enclosing_mount_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="find_enclosing_mount_finish" invoker="find_enclosing_mount_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous find mount request. +See g_file_find_enclosing_mount_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GMount for given @file or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="Mount" c:type="GMount*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_basename" invoker="get_basename"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="filename" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_child_for_display_name" invoker="get_child_for_display_name" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile to the specified child, or + %NULL if the display name couldn't be converted. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="display_name" transfer-ownership="none"> + <doc xml:space="preserve">string to a possible child</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_parent" invoker="get_parent"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_parse_name" invoker="get_parse_name"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a string containing the #GFile's parse name. + The returned string should be freed with g_free() + when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_path" invoker="get_path"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="filename" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_relative_path" invoker="get_relative_path"> + <doc xml:space="preserve">Gets the path for @descendant relative to @parent. + +This call does no blocking I/O.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="filename" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="parent" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="descendant" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_uri" invoker="get_uri"> + <doc xml:space="preserve">Gets the URI for the @file. + +This call does no blocking I/O.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a string containing the #GFile's URI. If the #GFile was constructed + with an invalid URI, an invalid URI is returned. + The returned string should be freed with g_free() + when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_uri_scheme" invoker="get_uri_scheme"> + <doc xml:space="preserve">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. + +The scheme can be different from the one used to construct the #GFile, +in that it might be replaced with one that is logically equivalent to the #GFile. + +This call does no blocking I/O.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a string containing the URI scheme for the given + #GFile or %NULL if the #GFile was constructed with an invalid URI. The + returned string should be freed with g_free() when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="has_uri_scheme" invoker="has_uri_scheme"> + <doc xml:space="preserve">Checks to see if a #GFile has a given URI scheme. + +This call does no blocking I/O.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if #GFile's backend supports the + given URI scheme, %FALSE if URI scheme is %NULL, + not supported, or #GFile is invalid.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="uri_scheme" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a URI scheme</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="hash" invoker="hash"> + <doc xml:space="preserve">Creates a hash value for a #GFile. + +This call does no blocking I/O.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">#gconstpointer to a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="is_native" invoker="is_native"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @file is native</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="make_directory" invoker="make_directory" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful creation, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="make_directory_async" invoker="make_directory_async" version="2.38"> + <doc xml:space="preserve">Asynchronously creates a directory.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="make_directory_finish" invoker="make_directory_finish" version="2.38" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous directory creation, started with +g_file_make_directory_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful directory creation, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="make_symbolic_link" invoker="make_symbolic_link" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on the creation of a new symlink, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile with the name of the symlink to create</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="symlink_value" transfer-ownership="none"> + <doc xml:space="preserve">a string with the path for the target + of the new symlink</doc> + <type name="filename" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="measure_disk_usage" invoker="measure_disk_usage" version="2.38" introspectable="0" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful, with the out parameters set. + %FALSE otherwise, with @error set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">#GFileMeasureFlags</doc> + <type name="FileMeasureFlags" c:type="GFileMeasureFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="progress_callback" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">a #GFileMeasureProgressCallback</doc> + <type name="FileMeasureProgressCallback" c:type="GFileMeasureProgressCallback"/> + </parameter> + <parameter name="progress_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user_data for @progress_callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="disk_usage" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of bytes of disk space used</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="num_dirs" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of directories encountered</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="num_files" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of non-directories encountered</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="measure_disk_usage_async" invoker="measure_disk_usage_async" version="2.38" introspectable="0"> + <doc xml:space="preserve">Recursively measures the disk usage of @file. + +This is the asynchronous version of g_file_measure_disk_usage(). See +there for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">#GFileMeasureFlags</doc> + <type name="FileMeasureFlags" c:type="GFileMeasureFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="progress_callback" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">a #GFileMeasureProgressCallback</doc> + <type name="FileMeasureProgressCallback" c:type="GFileMeasureProgressCallback"/> + </parameter> + <parameter name="progress_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user_data for @progress_callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when complete</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="measure_disk_usage_finish" invoker="measure_disk_usage_finish" version="2.38" throws="1"> + <doc xml:space="preserve">Collects the results from an earlier call to +g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for +more information.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful, with the out parameters set. + %FALSE otherwise, with @error set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="disk_usage" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of bytes of disk space used</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="num_dirs" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of directories encountered</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="num_files" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of non-directories encountered</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="monitor_dir" invoker="monitor_directory" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileMonitor for the given @file, + or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileMonitor" c:type="GFileMonitor*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileMonitorFlags</doc> + <type name="FileMonitorFlags" c:type="GFileMonitorFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="monitor_file" invoker="monitor_file" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileMonitor for the given @file, + or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileMonitor" c:type="GFileMonitor*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileMonitorFlags</doc> + <type name="FileMonitorFlags" c:type="GFileMonitorFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="mount_enclosing_volume" invoker="mount_enclosing_volume"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="location" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountMountFlags" c:type="GMountMountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation + or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="mount_enclosing_volume_finish" invoker="mount_enclosing_volume_finish" throws="1"> + <doc xml:space="preserve">Finishes a mount operation started by g_file_mount_enclosing_volume().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful. If an error has occurred, + this function will return %FALSE and set @error + appropriately if present.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="location" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="mount_mountable" invoker="mount_mountable"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountMountFlags" c:type="GMountMountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation, + or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="mount_mountable_finish" invoker="mount_mountable_finish" throws="1"> + <doc xml:space="preserve">Finishes a mount operation. See g_file_mount_mountable() for details. + +Finish an asynchronous mount operation that was started +with g_file_mount_mountable().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="move" invoker="move" throws="1"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful move, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">#GFile pointing to the source location</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="destination" transfer-ownership="none"> + <doc xml:space="preserve">#GFile pointing to the destination location</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">set of #GFileCopyFlags</doc> + <type name="FileCopyFlags" c:type="GFileCopyFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="progress_callback" transfer-ownership="none" nullable="1" allow-none="1" scope="call" closure="4"> + <doc xml:space="preserve">#GFileProgressCallback + function for updates</doc> + <type name="FileProgressCallback" c:type="GFileProgressCallback"/> + </parameter> + <parameter name="progress_callback_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">gpointer to user data for + the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="open_readwrite" invoker="open_readwrite" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFileIOStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">#GFile to open</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="open_readwrite_async" invoker="open_readwrite_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="open_readwrite_finish" invoker="open_readwrite_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file read operation started with +g_file_open_readwrite_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileIOStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="poll_mountable" invoker="poll_mountable" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="poll_mountable_finish" invoker="poll_mountable_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes a poll operation. See g_file_poll_mountable() for details. + +Finish an asynchronous poll operation that was polled +with g_file_poll_mountable().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation finished successfully. %FALSE +otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="prefix_matches" invoker="has_prefix"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @file's parent, grandparent, etc is @prefix, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="prefix" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="query_filesystem_info" invoker="query_filesystem_info" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo or %NULL if there was an error. + Free the returned object with g_object_unref().</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="query_filesystem_info_async" invoker="query_filesystem_info_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="query_filesystem_info_finish" invoker="query_filesystem_info_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous filesystem info query. +See g_file_query_filesystem_info_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFileInfo for given @file + or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="query_info" invoker="query_info" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo for the given @file, or %NULL + on error. Free the returned object with g_object_unref().</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="query_info_async" invoker="query_info_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the + request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="query_info_finish" invoker="query_info_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file info query. +See g_file_query_info_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFileInfo for given @file + or %NULL on error. Free the returned object with + g_object_unref().</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="query_settable_attributes" invoker="query_settable_attributes" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileAttributeInfoList describing the settable attributes. + When you are done with it, release it with + g_file_attribute_info_list_unref()</doc> + <type name="FileAttributeInfoList" c:type="GFileAttributeInfoList*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="query_writable_namespaces" invoker="query_writable_namespaces" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileAttributeInfoList describing the writable namespaces. + When you are done with it, release it with + g_file_attribute_info_list_unref()</doc> + <type name="FileAttributeInfoList" c:type="GFileAttributeInfoList*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="read_async" invoker="read_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="read_finish" invoker="read_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file read operation started with +g_file_read_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInputStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="read_fn" invoker="read" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFileInputStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">#GFile to read</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="replace" invoker="replace" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileOutputStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="etag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional [entity tag][gfile-etag] + for the current #GFile, or #NULL to ignore</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="make_backup" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a backup should be created</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="replace_async" invoker="replace_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="etag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an [entity tag][gfile-etag] for the current #GFile, + or %NULL to ignore</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="make_backup" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a backup should be created</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="replace_finish" invoker="replace_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file replace operation started with +g_file_replace_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileOutputStream, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="replace_readwrite" invoker="replace_readwrite" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileIOStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="etag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional [entity tag][gfile-etag] + for the current #GFile, or #NULL to ignore</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="make_backup" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a backup should be created</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="replace_readwrite_async" invoker="replace_readwrite_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="etag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an [entity tag][gfile-etag] for the current #GFile, + or %NULL to ignore</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="make_backup" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a backup should be created</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="replace_readwrite_finish" invoker="replace_readwrite_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file replace operation started with +g_file_replace_readwrite_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileIOStream, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="resolve_relative_path" invoker="resolve_relative_path"> + <doc xml:space="preserve">Resolves a relative path for @file to an absolute path. + +This call does no blocking I/O.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFile to the resolved path. + %NULL if @relative_path is %NULL or if @file is invalid. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="relative_path" transfer-ownership="none"> + <doc xml:space="preserve">a given relative path string</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="set_attribute" invoker="set_attribute" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the attribute was set, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a string containing the attribute's name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">The type of the attribute</doc> + <type name="FileAttributeType" c:type="GFileAttributeType"/> + </parameter> + <parameter name="value_p" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to the value (or the pointer + itself if the type is a pointer type)</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="set_attributes_async" invoker="set_attributes_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">a #gpointer</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="set_attributes_finish" invoker="set_attributes_finish" throws="1"> + <doc xml:space="preserve">Finishes setting an attribute started in g_file_set_attributes_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the attributes were set correctly, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="info" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo</doc> + <type name="FileInfo" c:type="GFileInfo**"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="set_attributes_from_info" invoker="set_attributes_from_info" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%FALSE if there was any error, %TRUE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">#GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="set_display_name" invoker="set_display_name" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile specifying what @file was renamed to, + or %NULL if there was an error. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="display_name" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="set_display_name_async" invoker="set_display_name_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="display_name" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="set_display_name_finish" invoker="set_display_name_finish" throws="1"> + <doc xml:space="preserve">Finishes setting a display name started with +g_file_set_display_name_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="start_mountable" invoker="start_mountable" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="DriveStartFlags" c:type="GDriveStartFlags"/> + </parameter> + <parameter name="start_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation, or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="start_mountable_finish" invoker="start_mountable_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes a start operation. See g_file_start_mountable() for details. + +Finish an asynchronous start operation that was started +with g_file_start_mountable().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation finished successfully. %FALSE +otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="stop_mountable" invoker="stop_mountable" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation, + or %NULL to avoid user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="stop_mountable_finish" invoker="stop_mountable_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes a stop operation, see g_file_stop_mountable() for details. + +Finish an asynchronous stop operation that was started +with g_file_stop_mountable().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation finished successfully. + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="trash" invoker="trash" throws="1"> + <doc xml:space="preserve">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. Since GLib 2.66, the `x-gvfs-notrash` unix +mount option can be used to disable g_file_trash() support for certain +mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case. + +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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful trash, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">#GFile to send to trash</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="trash_async" invoker="trash_async" version="2.38"> + <doc xml:space="preserve">Asynchronously sends @file to the Trash location, if possible.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="trash_finish" invoker="trash_finish" version="2.38" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file trashing operation, started with +g_file_trash_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful trash, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="unmount_mountable" invoker="unmount_mountable" deprecated="1" deprecated-version="2.22"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_file_unmount_mountable_with_operation() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="unmount_mountable_finish" invoker="unmount_mountable_finish" deprecated="1" deprecated-version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an unmount operation, see g_file_unmount_mountable() for details. + +Finish an asynchronous unmount operation that was started +with g_file_unmount_mountable().</doc> + <doc-deprecated xml:space="preserve">Use g_file_unmount_mountable_with_operation_finish() + instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation finished successfully. + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="unmount_mountable_with_operation" invoker="unmount_mountable_with_operation" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation, + or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="unmount_mountable_with_operation_finish" invoker="unmount_mountable_with_operation_finish" version="2.22" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation finished successfully. + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <method name="append_to" c:identifier="g_file_append_to" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileOutputStream, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="append_to_async" c:identifier="g_file_append_to_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="append_to_finish" c:identifier="g_file_append_to_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file append operation started with +g_file_append_to_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a valid #GFileOutputStream + or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">#GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="copy" c:identifier="g_file_copy" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="destination" transfer-ownership="none"> + <doc xml:space="preserve">destination #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">set of #GFileCopyFlags</doc> + <type name="FileCopyFlags" c:type="GFileCopyFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="progress_callback" transfer-ownership="none" nullable="1" allow-none="1" scope="call" closure="4"> + <doc xml:space="preserve">function to callback with + progress information, or %NULL if progress information is not needed</doc> + <type name="FileProgressCallback" c:type="GFileProgressCallback"/> + </parameter> + <parameter name="progress_callback_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to @progress_callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="copy_async" c:identifier="g_file_copy_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="destination" transfer-ownership="none"> + <doc xml:space="preserve">destination #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">set of #GFileCopyFlags</doc> + <type name="FileCopyFlags" c:type="GFileCopyFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="progress_callback" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="5"> + <doc xml:space="preserve">function to callback with progress + information, or %NULL if progress information is not needed</doc> + <type name="FileProgressCallback" c:type="GFileProgressCallback"/> + </parameter> + <parameter name="progress_callback_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data to pass to @progress_callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="7"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="copy_attributes" c:identifier="g_file_copy_attributes" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the attributes were copied successfully, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile with attributes</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="destination" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile to copy attributes to</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCopyFlags</doc> + <type name="FileCopyFlags" c:type="GFileCopyFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="copy_finish" c:identifier="g_file_copy_finish" throws="1"> + <doc xml:space="preserve">Finishes copying the file started with g_file_copy_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a %TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="create" c:identifier="g_file_create" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileOutputStream for the newly created + file, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="create_async" c:identifier="g_file_create_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="create_finish" c:identifier="g_file_create_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file create operation started with +g_file_create_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileOutputStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="create_readwrite" c:identifier="g_file_create_readwrite" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileIOStream for the newly created + file, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="create_readwrite_async" c:identifier="g_file_create_readwrite_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="create_readwrite_finish" c:identifier="g_file_create_readwrite_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file create operation started with +g_file_create_readwrite_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileIOStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="delete" c:identifier="g_file_delete" throws="1"> + <doc xml:space="preserve">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 @file doesn’t exist, %G_IO_ERROR_NOT_FOUND will be returned. This allows +for deletion to be implemented avoiding +[time-of-check to time-of-use races](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use): +|[ +g_autoptr(GError) local_error = NULL; +if (!g_file_delete (my_file, my_cancellable, &local_error) && + !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND)) + { + // deletion failed for some reason other than the file not existing: + // so report the error + g_warning ("Failed to delete %s: %s", + g_file_peek_path (my_file), local_error->message); + } +]| + +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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the file was deleted. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="delete_async" c:identifier="g_file_delete_async" version="2.34"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="delete_finish" c:identifier="g_file_delete_finish" version="2.34" throws="1"> + <doc xml:space="preserve">Finishes deleting a file started with g_file_delete_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the file was deleted. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="dup" c:identifier="g_file_dup"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile that is a duplicate + of the given #GFile.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="eject_mountable" c:identifier="g_file_eject_mountable" deprecated="1" deprecated-version="2.22"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_file_eject_mountable_with_operation() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="eject_mountable_finish" c:identifier="g_file_eject_mountable_finish" deprecated="1" deprecated-version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous eject operation started by +g_file_eject_mountable().</doc> + <doc-deprecated xml:space="preserve">Use g_file_eject_mountable_with_operation_finish() + instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @file was ejected successfully. + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="eject_mountable_with_operation" c:identifier="g_file_eject_mountable_with_operation" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation, + or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="eject_mountable_with_operation_finish" c:identifier="g_file_eject_mountable_with_operation_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous eject operation started by +g_file_eject_mountable_with_operation().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @file was ejected successfully. + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="enumerate_children" c:identifier="g_file_enumerate_children" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GFileEnumerator if successful, + %NULL on error. Free the returned object with g_object_unref().</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="enumerate_children_async" c:identifier="g_file_enumerate_children_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the + request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="enumerate_children_finish" c:identifier="g_file_enumerate_children_finish" throws="1"> + <doc xml:space="preserve">Finishes an async enumerate children operation. +See g_file_enumerate_children_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileEnumerator or %NULL + if an error occurred. + Free the returned object with g_object_unref().</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="equal" c:identifier="g_file_equal"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @file1 and @file2 are equal.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file1" transfer-ownership="none"> + <doc xml:space="preserve">the first #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="file2" transfer-ownership="none"> + <doc xml:space="preserve">the second #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </method> + <method name="find_enclosing_mount" c:identifier="g_file_find_enclosing_mount" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GMount where the @file is located + or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="Mount" c:type="GMount*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="find_enclosing_mount_async" c:identifier="g_file_find_enclosing_mount_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="find_enclosing_mount_finish" c:identifier="g_file_find_enclosing_mount_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous find mount request. +See g_file_find_enclosing_mount_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GMount for given @file or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="Mount" c:type="GMount*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="get_basename" c:identifier="g_file_get_basename"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="filename" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_child" c:identifier="g_file_get_child"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile to a child specified by @name. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">string containing the child's basename</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_child_for_display_name" c:identifier="g_file_get_child_for_display_name" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile to the specified child, or + %NULL if the display name couldn't be converted. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="display_name" transfer-ownership="none"> + <doc xml:space="preserve">string to a possible child</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_parent" c:identifier="g_file_get_parent"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_parse_name" c:identifier="g_file_get_parse_name"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a string containing the #GFile's parse name. + The returned string should be freed with g_free() + when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_path" c:identifier="g_file_get_path"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="filename" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_relative_path" c:identifier="g_file_get_relative_path"> + <doc xml:space="preserve">Gets the path for @descendant relative to @parent. + +This call does no blocking I/O.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="filename" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="parent" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="descendant" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </method> + <method name="get_uri" c:identifier="g_file_get_uri"> + <doc xml:space="preserve">Gets the URI for the @file. + +This call does no blocking I/O.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a string containing the #GFile's URI. If the #GFile was constructed + with an invalid URI, an invalid URI is returned. + The returned string should be freed with g_free() + when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_uri_scheme" c:identifier="g_file_get_uri_scheme"> + <doc xml:space="preserve">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. + +The scheme can be different from the one used to construct the #GFile, +in that it might be replaced with one that is logically equivalent to the #GFile. + +This call does no blocking I/O.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a string containing the URI scheme for the given + #GFile or %NULL if the #GFile was constructed with an invalid URI. The + returned string should be freed with g_free() when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="has_parent" c:identifier="g_file_has_parent" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @file is an immediate child of @parent (or any parent in + the case that @parent is %NULL).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="parent" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the parent to check for, or %NULL</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </method> + <method name="has_prefix" c:identifier="g_file_has_prefix"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @file's parent, grandparent, etc is @prefix, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="prefix" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </method> + <method name="has_uri_scheme" c:identifier="g_file_has_uri_scheme"> + <doc xml:space="preserve">Checks to see if a #GFile has a given URI scheme. + +This call does no blocking I/O.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if #GFile's backend supports the + given URI scheme, %FALSE if URI scheme is %NULL, + not supported, or #GFile is invalid.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="uri_scheme" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a URI scheme</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="hash" c:identifier="g_file_hash"> + <doc xml:space="preserve">Creates a hash value for a #GFile. + +This call does no blocking I/O.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">#gconstpointer to a #GFile</doc> + <type name="File" c:type="gconstpointer"/> + </instance-parameter> + </parameters> + </method> + <method name="is_native" c:identifier="g_file_is_native"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @file is native</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="load_bytes" c:identifier="g_file_load_bytes" version="2.56" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GBytes or %NULL and @error is set</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="etag_out" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to place the current + entity tag for the file, or %NULL if the entity tag is not needed</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </method> + <method name="load_bytes_async" c:identifier="g_file_load_bytes_async" version="2.56"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the + request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="load_bytes_finish" c:identifier="g_file_load_bytes_finish" version="2.56" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GBytes or %NULL and @error is set</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult provided to the callback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="etag_out" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to place the current + entity tag for the file, or %NULL if the entity tag is not needed</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </method> + <method name="load_contents" c:identifier="g_file_load_contents" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @file's contents were successfully loaded. + %FALSE if there were errors.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="contents" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">a location to place the contents of the file</doc> + <array length="2" zero-terminated="0" c:type="char**"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to place the length of the contents of the file, + or %NULL if the length is not needed</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="etag_out" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to place the current entity tag for the file, + or %NULL if the entity tag is not needed</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="load_contents_async" c:identifier="g_file_load_contents_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="load_contents_finish" c:identifier="g_file_load_contents_finish" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the load was successful. If %FALSE and @error is + present, it will be set appropriately.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="contents" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">a location to place the contents of the file</doc> + <array length="2" zero-terminated="0" c:type="char**"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to place the length of the contents of the file, + or %NULL if the length is not needed</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="etag_out" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to place the current entity tag for the file, + or %NULL if the entity tag is not needed</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="load_partial_contents_async" c:identifier="g_file_load_partial_contents_async" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="read_more_callback" transfer-ownership="none" scope="call" closure="3"> + <doc xml:space="preserve">a + #GFileReadMoreCallback to receive partial data + and to specify whether further data should be read</doc> + <type name="FileReadMoreCallback" c:type="GFileReadMoreCallback"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to the callback functions</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="load_partial_contents_finish" c:identifier="g_file_load_partial_contents_finish" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the load was successful. If %FALSE and @error is + present, it will be set appropriately.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="contents" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">a location to place the contents of the file</doc> + <array length="2" zero-terminated="0" c:type="char**"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to place the length of the contents of the file, + or %NULL if the length is not needed</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="etag_out" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to place the current entity tag for the file, + or %NULL if the entity tag is not needed</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="make_directory" c:identifier="g_file_make_directory" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful creation, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="make_directory_async" c:identifier="g_file_make_directory_async" version="2.38"> + <doc xml:space="preserve">Asynchronously creates a directory.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="make_directory_finish" c:identifier="g_file_make_directory_finish" version="2.38" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous directory creation, started with +g_file_make_directory_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful directory creation, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="make_directory_with_parents" c:identifier="g_file_make_directory_with_parents" version="2.18" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if all directories have been successfully created, %FALSE +otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="make_symbolic_link" c:identifier="g_file_make_symbolic_link" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on the creation of a new symlink, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile with the name of the symlink to create</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="symlink_value" transfer-ownership="none"> + <doc xml:space="preserve">a string with the path for the target + of the new symlink</doc> + <type name="filename" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="measure_disk_usage" c:identifier="g_file_measure_disk_usage" version="2.38" introspectable="0" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful, with the out parameters set. + %FALSE otherwise, with @error set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">#GFileMeasureFlags</doc> + <type name="FileMeasureFlags" c:type="GFileMeasureFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="progress_callback" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">a #GFileMeasureProgressCallback</doc> + <type name="FileMeasureProgressCallback" c:type="GFileMeasureProgressCallback"/> + </parameter> + <parameter name="progress_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user_data for @progress_callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="disk_usage" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of bytes of disk space used</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="num_dirs" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of directories encountered</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="num_files" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of non-directories encountered</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + </parameters> + </method> + <method name="measure_disk_usage_async" c:identifier="g_file_measure_disk_usage_async" version="2.38" introspectable="0"> + <doc xml:space="preserve">Recursively measures the disk usage of @file. + +This is the asynchronous version of g_file_measure_disk_usage(). See +there for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">#GFileMeasureFlags</doc> + <type name="FileMeasureFlags" c:type="GFileMeasureFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="progress_callback" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">a #GFileMeasureProgressCallback</doc> + <type name="FileMeasureProgressCallback" c:type="GFileMeasureProgressCallback"/> + </parameter> + <parameter name="progress_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user_data for @progress_callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when complete</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="measure_disk_usage_finish" c:identifier="g_file_measure_disk_usage_finish" version="2.38" throws="1"> + <doc xml:space="preserve">Collects the results from an earlier call to +g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for +more information.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful, with the out parameters set. + %FALSE otherwise, with @error set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="disk_usage" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of bytes of disk space used</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="num_dirs" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of directories encountered</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="num_files" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of non-directories encountered</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + </parameters> + </method> + <method name="monitor" c:identifier="g_file_monitor" version="2.18" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileMonitor for the given @file, + or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileMonitor" c:type="GFileMonitor*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileMonitorFlags</doc> + <type name="FileMonitorFlags" c:type="GFileMonitorFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="monitor_directory" c:identifier="g_file_monitor_directory" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileMonitor for the given @file, + or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileMonitor" c:type="GFileMonitor*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileMonitorFlags</doc> + <type name="FileMonitorFlags" c:type="GFileMonitorFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="monitor_file" c:identifier="g_file_monitor_file" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileMonitor for the given @file, + or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileMonitor" c:type="GFileMonitor*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileMonitorFlags</doc> + <type name="FileMonitorFlags" c:type="GFileMonitorFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="mount_enclosing_volume" c:identifier="g_file_mount_enclosing_volume"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="location" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountMountFlags" c:type="GMountMountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation + or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="mount_enclosing_volume_finish" c:identifier="g_file_mount_enclosing_volume_finish" throws="1"> + <doc xml:space="preserve">Finishes a mount operation started by g_file_mount_enclosing_volume().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful. If an error has occurred, + this function will return %FALSE and set @error + appropriately if present.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="location" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="mount_mountable" c:identifier="g_file_mount_mountable"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountMountFlags" c:type="GMountMountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation, + or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="mount_mountable_finish" c:identifier="g_file_mount_mountable_finish" throws="1"> + <doc xml:space="preserve">Finishes a mount operation. See g_file_mount_mountable() for details. + +Finish an asynchronous mount operation that was started +with g_file_mount_mountable().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="move" c:identifier="g_file_move" throws="1"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful move, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">#GFile pointing to the source location</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="destination" transfer-ownership="none"> + <doc xml:space="preserve">#GFile pointing to the destination location</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">set of #GFileCopyFlags</doc> + <type name="FileCopyFlags" c:type="GFileCopyFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="progress_callback" transfer-ownership="none" nullable="1" allow-none="1" scope="call" closure="4"> + <doc xml:space="preserve">#GFileProgressCallback + function for updates</doc> + <type name="FileProgressCallback" c:type="GFileProgressCallback"/> + </parameter> + <parameter name="progress_callback_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">gpointer to user data for + the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="open_readwrite" c:identifier="g_file_open_readwrite" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFileIOStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">#GFile to open</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="open_readwrite_async" c:identifier="g_file_open_readwrite_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="open_readwrite_finish" c:identifier="g_file_open_readwrite_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file read operation started with +g_file_open_readwrite_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileIOStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="peek_path" c:identifier="g_file_peek_path" version="2.56"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">string containing the #GFile's path, + or %NULL if no such path exists. The returned string is owned by @file.</doc> + <type name="filename" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="poll_mountable" c:identifier="g_file_poll_mountable" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="poll_mountable_finish" c:identifier="g_file_poll_mountable_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes a poll operation. See g_file_poll_mountable() for details. + +Finish an asynchronous poll operation that was polled +with g_file_poll_mountable().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation finished successfully. %FALSE +otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="query_default_handler" c:identifier="g_file_query_default_handler" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GAppInfo if the handle was found, + %NULL if there were errors. + When you are done with it, release it with g_object_unref()</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile to open</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="query_default_handler_async" c:identifier="g_file_query_default_handler_async" version="2.60"> + <doc xml:space="preserve">Async version of g_file_query_default_handler().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile to open</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is done</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="query_default_handler_finish" c:identifier="g_file_query_default_handler_finish" version="2.60" throws="1"> + <doc xml:space="preserve">Finishes a g_file_query_default_handler_async() operation.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GAppInfo if the handle was found, + %NULL if there were errors. + When you are done with it, release it with g_object_unref()</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile to open</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="query_exists" c:identifier="g_file_query_exists"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the file exists (and can be detected without error), + %FALSE otherwise (or if cancelled).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="query_file_type" c:identifier="g_file_query_file_type" version="2.18"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The #GFileType of the file and #G_FILE_TYPE_UNKNOWN + if the file does not exist</doc> + <type name="FileType" c:type="GFileType"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileQueryInfoFlags passed to g_file_query_info()</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="query_filesystem_info" c:identifier="g_file_query_filesystem_info" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo or %NULL if there was an error. + Free the returned object with g_object_unref().</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="query_filesystem_info_async" c:identifier="g_file_query_filesystem_info_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="query_filesystem_info_finish" c:identifier="g_file_query_filesystem_info_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous filesystem info query. +See g_file_query_filesystem_info_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFileInfo for given @file + or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="query_info" c:identifier="g_file_query_info" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo for the given @file, or %NULL + on error. Free the returned object with g_object_unref().</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="query_info_async" c:identifier="g_file_query_info_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the + request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="query_info_finish" c:identifier="g_file_query_info_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file info query. +See g_file_query_info_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFileInfo for given @file + or %NULL on error. Free the returned object with + g_object_unref().</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="query_settable_attributes" c:identifier="g_file_query_settable_attributes" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileAttributeInfoList describing the settable attributes. + When you are done with it, release it with + g_file_attribute_info_list_unref()</doc> + <type name="FileAttributeInfoList" c:type="GFileAttributeInfoList*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="query_writable_namespaces" c:identifier="g_file_query_writable_namespaces" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileAttributeInfoList describing the writable namespaces. + When you are done with it, release it with + g_file_attribute_info_list_unref()</doc> + <type name="FileAttributeInfoList" c:type="GFileAttributeInfoList*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read" c:identifier="g_file_read" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFileInputStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">#GFile to read</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_async" c:identifier="g_file_read_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="read_finish" c:identifier="g_file_read_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file read operation started with +g_file_read_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInputStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="replace" c:identifier="g_file_replace" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileOutputStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="etag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional [entity tag][gfile-etag] + for the current #GFile, or #NULL to ignore</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="make_backup" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a backup should be created</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="replace_async" c:identifier="g_file_replace_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="etag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an [entity tag][gfile-etag] for the current #GFile, + or %NULL to ignore</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="make_backup" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a backup should be created</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="replace_contents" c:identifier="g_file_replace_contents" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful. If an error has occurred, this function + will return %FALSE and set @error appropriately if present.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="contents" transfer-ownership="none"> + <doc xml:space="preserve">a string containing the new contents for @file</doc> + <array length="1" zero-terminated="0" c:type="const char*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @contents in bytes</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="etag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the old [entity-tag][gfile-etag] for the document, + or %NULL</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="make_backup" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a backup should be created</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="new_etag" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">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</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="replace_contents_async" c:identifier="g_file_replace_contents_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="contents" transfer-ownership="none"> + <doc xml:space="preserve">string of contents to replace the file with</doc> + <array length="1" zero-terminated="0" c:type="const char*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @contents in bytes</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="etag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a new [entity tag][gfile-etag] for the @file, or %NULL</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="make_backup" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a backup should be created</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="7"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="replace_contents_bytes_async" c:identifier="g_file_replace_contents_bytes_async" version="2.40"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="contents" transfer-ownership="none"> + <doc xml:space="preserve">a #GBytes</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="etag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a new [entity tag][gfile-etag] for the @file, or %NULL</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="make_backup" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a backup should be created</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="replace_contents_finish" c:identifier="g_file_replace_contents_finish" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on failure.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="new_etag" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">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</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="replace_finish" c:identifier="g_file_replace_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file replace operation started with +g_file_replace_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileOutputStream, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="replace_readwrite" c:identifier="g_file_replace_readwrite" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileIOStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="etag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional [entity tag][gfile-etag] + for the current #GFile, or #NULL to ignore</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="make_backup" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a backup should be created</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="replace_readwrite_async" c:identifier="g_file_replace_readwrite_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="etag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an [entity tag][gfile-etag] for the current #GFile, + or %NULL to ignore</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="make_backup" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a backup should be created</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="replace_readwrite_finish" c:identifier="g_file_replace_readwrite_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file replace operation started with +g_file_replace_readwrite_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileIOStream, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="resolve_relative_path" c:identifier="g_file_resolve_relative_path"> + <doc xml:space="preserve">Resolves a relative path for @file to an absolute path. + +This call does no blocking I/O.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFile to the resolved path. + %NULL if @relative_path is %NULL or if @file is invalid. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="relative_path" transfer-ownership="none"> + <doc xml:space="preserve">a given relative path string</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_attribute" c:identifier="g_file_set_attribute" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the attribute was set, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a string containing the attribute's name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">The type of the attribute</doc> + <type name="FileAttributeType" c:type="GFileAttributeType"/> + </parameter> + <parameter name="value_p" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to the value (or the pointer + itself if the type is a pointer type)</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_attribute_byte_string" c:identifier="g_file_set_attribute_byte_string" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @attribute was successfully set to @value + in the @file, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a string containing the attribute's name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a string containing the attribute's new value</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_attribute_int32" c:identifier="g_file_set_attribute_int32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @attribute was successfully set to @value + in the @file, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a string containing the attribute's name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #gint32 containing the attribute's new value</doc> + <type name="gint32" c:type="gint32"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_attribute_int64" c:identifier="g_file_set_attribute_int64" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @attribute was successfully set, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a string containing the attribute's name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #guint64 containing the attribute's new value</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_attribute_string" c:identifier="g_file_set_attribute_string" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @attribute was successfully set, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a string containing the attribute's name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a string containing the attribute's value</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">#GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_attribute_uint32" c:identifier="g_file_set_attribute_uint32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @attribute was successfully set to @value + in the @file, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a string containing the attribute's name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #guint32 containing the attribute's new value</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_attribute_uint64" c:identifier="g_file_set_attribute_uint64" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @attribute was successfully set to @value + in the @file, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a string containing the attribute's name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #guint64 containing the attribute's new value</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_attributes_async" c:identifier="g_file_set_attributes_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #gpointer</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="set_attributes_finish" c:identifier="g_file_set_attributes_finish" throws="1"> + <doc xml:space="preserve">Finishes setting an attribute started in g_file_set_attributes_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the attributes were set correctly, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="info" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo</doc> + <type name="FileInfo" c:type="GFileInfo**"/> + </parameter> + </parameters> + </method> + <method name="set_attributes_from_info" c:identifier="g_file_set_attributes_from_info" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%FALSE if there was any error, %TRUE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">#GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_display_name" c:identifier="g_file_set_display_name" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile specifying what @file was renamed to, + or %NULL if there was an error. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="display_name" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_display_name_async" c:identifier="g_file_set_display_name_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="display_name" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="set_display_name_finish" c:identifier="g_file_set_display_name_finish" throws="1"> + <doc xml:space="preserve">Finishes setting a display name started with +g_file_set_display_name_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="start_mountable" c:identifier="g_file_start_mountable" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="DriveStartFlags" c:type="GDriveStartFlags"/> + </parameter> + <parameter name="start_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation, or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="start_mountable_finish" c:identifier="g_file_start_mountable_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes a start operation. See g_file_start_mountable() for details. + +Finish an asynchronous start operation that was started +with g_file_start_mountable().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation finished successfully. %FALSE +otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="stop_mountable" c:identifier="g_file_stop_mountable" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation, + or %NULL to avoid user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="stop_mountable_finish" c:identifier="g_file_stop_mountable_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes a stop operation, see g_file_stop_mountable() for details. + +Finish an asynchronous stop operation that was started +with g_file_stop_mountable().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation finished successfully. + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="supports_thread_contexts" c:identifier="g_file_supports_thread_contexts" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Whether or not @file supports thread-default contexts.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="trash" c:identifier="g_file_trash" throws="1"> + <doc xml:space="preserve">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. Since GLib 2.66, the `x-gvfs-notrash` unix +mount option can be used to disable g_file_trash() support for certain +mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case. + +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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful trash, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">#GFile to send to trash</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="trash_async" c:identifier="g_file_trash_async" version="2.38"> + <doc xml:space="preserve">Asynchronously sends @file to the Trash location, if possible.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="trash_finish" c:identifier="g_file_trash_finish" version="2.38" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous file trashing operation, started with +g_file_trash_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful trash, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="unmount_mountable" c:identifier="g_file_unmount_mountable" deprecated="1" deprecated-version="2.22"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_file_unmount_mountable_with_operation() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="unmount_mountable_finish" c:identifier="g_file_unmount_mountable_finish" deprecated="1" deprecated-version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an unmount operation, see g_file_unmount_mountable() for details. + +Finish an asynchronous unmount operation that was started +with g_file_unmount_mountable().</doc> + <doc-deprecated xml:space="preserve">Use g_file_unmount_mountable_with_operation_finish() + instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation finished successfully. + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="unmount_mountable_with_operation" c:identifier="g_file_unmount_mountable_with_operation" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation, + or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="unmount_mountable_with_operation_finish" c:identifier="g_file_unmount_mountable_with_operation_finish" version="2.22" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation finished successfully. + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + </interface> + <record name="FileAttributeInfo" c:type="GFileAttributeInfo"> + <doc xml:space="preserve">Information about a specific attribute.</doc> + <field name="name" writable="1"> + <doc xml:space="preserve">the name of the attribute.</doc> + <type name="utf8" c:type="char*"/> + </field> + <field name="type" writable="1"> + <doc xml:space="preserve">the #GFileAttributeType type of the attribute.</doc> + <type name="FileAttributeType" c:type="GFileAttributeType"/> + </field> + <field name="flags" writable="1"> + <doc xml:space="preserve">a set of #GFileAttributeInfoFlags.</doc> + <type name="FileAttributeInfoFlags" c:type="GFileAttributeInfoFlags"/> + </field> + </record> + <bitfield name="FileAttributeInfoFlags" glib:type-name="GFileAttributeInfoFlags" glib:get-type="g_file_attribute_info_flags_get_type" c:type="GFileAttributeInfoFlags"> + <doc xml:space="preserve">Flags specifying the behaviour of an attribute.</doc> + <member name="none" value="0" c:identifier="G_FILE_ATTRIBUTE_INFO_NONE" glib:nick="none"> + <doc xml:space="preserve">no flags set.</doc> + </member> + <member name="copy_with_file" value="1" c:identifier="G_FILE_ATTRIBUTE_INFO_COPY_WITH_FILE" glib:nick="copy-with-file"> + <doc xml:space="preserve">copy the attribute values when the file is copied.</doc> + </member> + <member name="copy_when_moved" value="2" c:identifier="G_FILE_ATTRIBUTE_INFO_COPY_WHEN_MOVED" glib:nick="copy-when-moved"> + <doc xml:space="preserve">copy the attribute values when the file is moved.</doc> + </member> + </bitfield> + <record name="FileAttributeInfoList" c:type="GFileAttributeInfoList" glib:type-name="GFileAttributeInfoList" glib:get-type="g_file_attribute_info_list_get_type" c:symbol-prefix="file_attribute_info_list"> + <doc xml:space="preserve">Acts as a lightweight registry for possible valid file attributes. +The registry stores Key-Value pair formats as #GFileAttributeInfos.</doc> + <field name="infos" writable="1"> + <doc xml:space="preserve">an array of #GFileAttributeInfos.</doc> + <type name="FileAttributeInfo" c:type="GFileAttributeInfo*"/> + </field> + <field name="n_infos" writable="1"> + <doc xml:space="preserve">the number of values in the array.</doc> + <type name="gint" c:type="int"/> + </field> + <constructor name="new" c:identifier="g_file_attribute_info_list_new"> + <doc xml:space="preserve">Creates a new file attribute info list.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileAttributeInfoList.</doc> + <type name="FileAttributeInfoList" c:type="GFileAttributeInfoList*"/> + </return-value> + </constructor> + <method name="add" c:identifier="g_file_attribute_info_list_add"> + <doc xml:space="preserve">Adds a new attribute with @name to the @list, setting +its @type and @flags.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileAttributeInfoList.</doc> + <type name="FileAttributeInfoList" c:type="GFileAttributeInfoList*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the attribute to add.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">the #GFileAttributeType for the attribute.</doc> + <type name="FileAttributeType" c:type="GFileAttributeType"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">#GFileAttributeInfoFlags for the attribute.</doc> + <type name="FileAttributeInfoFlags" c:type="GFileAttributeInfoFlags"/> + </parameter> + </parameters> + </method> + <method name="dup" c:identifier="g_file_attribute_info_list_dup"> + <doc xml:space="preserve">Makes a duplicate of a file attribute info list.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a copy of the given @list.</doc> + <type name="FileAttributeInfoList" c:type="GFileAttributeInfoList*"/> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileAttributeInfoList to duplicate.</doc> + <type name="FileAttributeInfoList" c:type="GFileAttributeInfoList*"/> + </instance-parameter> + </parameters> + </method> + <method name="lookup" c:identifier="g_file_attribute_info_list_lookup"> + <doc xml:space="preserve">Gets the file attribute with the name @name from @list.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GFileAttributeInfo for the @name, or %NULL if an +attribute isn't found.</doc> + <type name="FileAttributeInfo" c:type="const GFileAttributeInfo*"/> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileAttributeInfoList.</doc> + <type name="FileAttributeInfoList" c:type="GFileAttributeInfoList*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the attribute to look up.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_file_attribute_info_list_ref"> + <doc xml:space="preserve">References a file attribute info list.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFileAttributeInfoList or %NULL on error.</doc> + <type name="FileAttributeInfoList" c:type="GFileAttributeInfoList*"/> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileAttributeInfoList to reference.</doc> + <type name="FileAttributeInfoList" c:type="GFileAttributeInfoList*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_file_attribute_info_list_unref"> + <doc xml:space="preserve">Removes a reference from the given @list. If the reference count +falls to zero, the @list is deleted.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">The #GFileAttributeInfoList to unreference.</doc> + <type name="FileAttributeInfoList" c:type="GFileAttributeInfoList*"/> + </instance-parameter> + </parameters> + </method> + </record> + <record name="FileAttributeMatcher" c:type="GFileAttributeMatcher" glib:type-name="GFileAttributeMatcher" glib:get-type="g_file_attribute_matcher_get_type" c:symbol-prefix="file_attribute_matcher"> + <doc xml:space="preserve">Determines if a string matches a file attribute.</doc> + <constructor name="new" c:identifier="g_file_attribute_matcher_new"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileAttributeMatcher</doc> + <type name="FileAttributeMatcher" c:type="GFileAttributeMatcher*"/> + </return-value> + <parameters> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute string to match.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </constructor> + <method name="enumerate_namespace" c:identifier="g_file_attribute_matcher_enumerate_namespace"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the matcher matches all of the entries +in the given @ns, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="matcher" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileAttributeMatcher.</doc> + <type name="FileAttributeMatcher" c:type="GFileAttributeMatcher*"/> + </instance-parameter> + <parameter name="ns" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a file attribute namespace.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="enumerate_next" c:identifier="g_file_attribute_matcher_enumerate_next"> + <doc xml:space="preserve">Gets the next matched attribute from a #GFileAttributeMatcher.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing the next attribute or, %NULL if +no more attribute exist.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="matcher" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileAttributeMatcher.</doc> + <type name="FileAttributeMatcher" c:type="GFileAttributeMatcher*"/> + </instance-parameter> + </parameters> + </method> + <method name="matches" c:identifier="g_file_attribute_matcher_matches"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @attribute matches @matcher. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="matcher" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileAttributeMatcher.</doc> + <type name="FileAttributeMatcher" c:type="GFileAttributeMatcher*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="matches_only" c:identifier="g_file_attribute_matcher_matches_only"> + <doc xml:space="preserve">Checks if a attribute matcher only matches a given attribute. Always +returns %FALSE if "*" was used when creating the matcher.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the matcher only matches @attribute. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="matcher" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileAttributeMatcher.</doc> + <type name="FileAttributeMatcher" c:type="GFileAttributeMatcher*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_file_attribute_matcher_ref"> + <doc xml:space="preserve">References a file attribute matcher.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileAttributeMatcher.</doc> + <type name="FileAttributeMatcher" c:type="GFileAttributeMatcher*"/> + </return-value> + <parameters> + <instance-parameter name="matcher" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileAttributeMatcher.</doc> + <type name="FileAttributeMatcher" c:type="GFileAttributeMatcher*"/> + </instance-parameter> + </parameters> + </method> + <method name="subtract" c:identifier="g_file_attribute_matcher_subtract"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">A file attribute matcher matching all attributes of + @matcher that are not matched by @subtract</doc> + <type name="FileAttributeMatcher" c:type="GFileAttributeMatcher*"/> + </return-value> + <parameters> + <instance-parameter name="matcher" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Matcher to subtract from</doc> + <type name="FileAttributeMatcher" c:type="GFileAttributeMatcher*"/> + </instance-parameter> + <parameter name="subtract" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The matcher to subtract</doc> + <type name="FileAttributeMatcher" c:type="GFileAttributeMatcher*"/> + </parameter> + </parameters> + </method> + <method name="to_string" c:identifier="g_file_attribute_matcher_to_string" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a string describing the attributes the matcher matches + against or %NULL if @matcher was %NULL.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="matcher" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GFileAttributeMatcher.</doc> + <type name="FileAttributeMatcher" c:type="GFileAttributeMatcher*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_file_attribute_matcher_unref"> + <doc xml:space="preserve">Unreferences @matcher. If the reference count falls below 1, +the @matcher is automatically freed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="matcher" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileAttributeMatcher.</doc> + <type name="FileAttributeMatcher" c:type="GFileAttributeMatcher*"/> + </instance-parameter> + </parameters> + </method> + </record> + <enumeration name="FileAttributeStatus" glib:type-name="GFileAttributeStatus" glib:get-type="g_file_attribute_status_get_type" c:type="GFileAttributeStatus"> + <doc xml:space="preserve">Used by g_file_set_attributes_from_info() when setting file attributes.</doc> + <member name="unset" value="0" c:identifier="G_FILE_ATTRIBUTE_STATUS_UNSET" glib:nick="unset"> + <doc xml:space="preserve">Attribute value is unset (empty).</doc> + </member> + <member name="set" value="1" c:identifier="G_FILE_ATTRIBUTE_STATUS_SET" glib:nick="set"> + <doc xml:space="preserve">Attribute value is set.</doc> + </member> + <member name="error_setting" value="2" c:identifier="G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING" glib:nick="error-setting"> + <doc xml:space="preserve">Indicates an error in setting the value.</doc> + </member> + </enumeration> + <enumeration name="FileAttributeType" glib:type-name="GFileAttributeType" glib:get-type="g_file_attribute_type_get_type" c:type="GFileAttributeType"> + <doc xml:space="preserve">The data types for file attributes.</doc> + <member name="invalid" value="0" c:identifier="G_FILE_ATTRIBUTE_TYPE_INVALID" glib:nick="invalid"> + <doc xml:space="preserve">indicates an invalid or uninitialized type.</doc> + </member> + <member name="string" value="1" c:identifier="G_FILE_ATTRIBUTE_TYPE_STRING" glib:nick="string"> + <doc xml:space="preserve">a null terminated UTF8 string.</doc> + </member> + <member name="byte_string" value="2" c:identifier="G_FILE_ATTRIBUTE_TYPE_BYTE_STRING" glib:nick="byte-string"> + <doc xml:space="preserve">a zero terminated string of non-zero bytes.</doc> + </member> + <member name="boolean" value="3" c:identifier="G_FILE_ATTRIBUTE_TYPE_BOOLEAN" glib:nick="boolean"> + <doc xml:space="preserve">a boolean value.</doc> + </member> + <member name="uint32" value="4" c:identifier="G_FILE_ATTRIBUTE_TYPE_UINT32" glib:nick="uint32"> + <doc xml:space="preserve">an unsigned 4-byte/32-bit integer.</doc> + </member> + <member name="int32" value="5" c:identifier="G_FILE_ATTRIBUTE_TYPE_INT32" glib:nick="int32"> + <doc xml:space="preserve">a signed 4-byte/32-bit integer.</doc> + </member> + <member name="uint64" value="6" c:identifier="G_FILE_ATTRIBUTE_TYPE_UINT64" glib:nick="uint64"> + <doc xml:space="preserve">an unsigned 8-byte/64-bit integer.</doc> + </member> + <member name="int64" value="7" c:identifier="G_FILE_ATTRIBUTE_TYPE_INT64" glib:nick="int64"> + <doc xml:space="preserve">a signed 8-byte/64-bit integer.</doc> + </member> + <member name="object" value="8" c:identifier="G_FILE_ATTRIBUTE_TYPE_OBJECT" glib:nick="object"> + <doc xml:space="preserve">a #GObject.</doc> + </member> + <member name="stringv" value="9" c:identifier="G_FILE_ATTRIBUTE_TYPE_STRINGV" glib:nick="stringv"> + <doc xml:space="preserve">a %NULL terminated char **. Since 2.22</doc> + </member> + </enumeration> + <bitfield name="FileCopyFlags" glib:type-name="GFileCopyFlags" glib:get-type="g_file_copy_flags_get_type" c:type="GFileCopyFlags"> + <doc xml:space="preserve">Flags used when copying or moving files.</doc> + <member name="none" value="0" c:identifier="G_FILE_COPY_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="overwrite" value="1" c:identifier="G_FILE_COPY_OVERWRITE" glib:nick="overwrite"> + <doc xml:space="preserve">Overwrite any existing files</doc> + </member> + <member name="backup" value="2" c:identifier="G_FILE_COPY_BACKUP" glib:nick="backup"> + <doc xml:space="preserve">Make a backup of any existing files.</doc> + </member> + <member name="nofollow_symlinks" value="4" c:identifier="G_FILE_COPY_NOFOLLOW_SYMLINKS" glib:nick="nofollow-symlinks"> + <doc xml:space="preserve">Don't follow symlinks.</doc> + </member> + <member name="all_metadata" value="8" c:identifier="G_FILE_COPY_ALL_METADATA" glib:nick="all-metadata"> + <doc xml:space="preserve">Copy all file metadata instead of just default set used for copy (see #GFileInfo).</doc> + </member> + <member name="no_fallback_for_move" value="16" c:identifier="G_FILE_COPY_NO_FALLBACK_FOR_MOVE" glib:nick="no-fallback-for-move"> + <doc xml:space="preserve">Don't use copy and delete fallback if native move not supported.</doc> + </member> + <member name="target_default_perms" value="32" c:identifier="G_FILE_COPY_TARGET_DEFAULT_PERMS" glib:nick="target-default-perms"> + <doc xml:space="preserve">Leaves target file with default perms, instead of setting the source file perms.</doc> + </member> + </bitfield> + <bitfield name="FileCreateFlags" glib:type-name="GFileCreateFlags" glib:get-type="g_file_create_flags_get_type" c:type="GFileCreateFlags"> + <doc xml:space="preserve">Flags used when an operation may create a file.</doc> + <member name="none" value="0" c:identifier="G_FILE_CREATE_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="private" value="1" c:identifier="G_FILE_CREATE_PRIVATE" glib:nick="private"> + <doc xml:space="preserve">Create a file that can only be + accessed by the current user.</doc> + </member> + <member name="replace_destination" value="2" c:identifier="G_FILE_CREATE_REPLACE_DESTINATION" glib:nick="replace-destination"> + <doc xml:space="preserve">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. This flag can only be used with + g_file_replace() and its variants, including g_file_replace_contents(). + Since 2.20</doc> + </member> + </bitfield> + <interface name="FileDescriptorBased" c:symbol-prefix="file_descriptor_based" c:type="GFileDescriptorBased" version="2.24" glib:type-name="GFileDescriptorBased" glib:get-type="g_file_descriptor_based_get_type" glib:type-struct="FileDescriptorBasedIface"> + <doc xml:space="preserve">#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.</doc> + <virtual-method name="get_fd" invoker="get_fd" version="2.24"> + <doc xml:space="preserve">Gets the underlying file descriptor.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The file descriptor</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="fd_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileDescriptorBased.</doc> + <type name="FileDescriptorBased" c:type="GFileDescriptorBased*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="get_fd" c:identifier="g_file_descriptor_based_get_fd" version="2.24"> + <doc xml:space="preserve">Gets the underlying file descriptor.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The file descriptor</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="fd_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileDescriptorBased.</doc> + <type name="FileDescriptorBased" c:type="GFileDescriptorBased*"/> + </instance-parameter> + </parameters> + </method> + </interface> + <record name="FileDescriptorBasedIface" c:type="GFileDescriptorBasedIface" glib:is-gtype-struct-for="FileDescriptorBased"> + <doc xml:space="preserve">An interface for file descriptor based io objects.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="get_fd"> + <callback name="get_fd"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The file descriptor</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <parameter name="fd_based" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileDescriptorBased.</doc> + <type name="FileDescriptorBased" c:type="GFileDescriptorBased*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="FileEnumerator" c:symbol-prefix="file_enumerator" c:type="GFileEnumerator" parent="GObject.Object" glib:type-name="GFileEnumerator" glib:get-type="g_file_enumerator_get_type" glib:type-struct="FileEnumeratorClass"> + <doc xml:space="preserve">#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().</doc> + <virtual-method name="close_async" invoker="close_async"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="close_finish" invoker="close_finish" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the close operation has finished successfully.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="close_fn" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="next_file" invoker="next_file" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">A #GFileInfo or %NULL on error + or end of enumerator. Free the returned object with + g_object_unref() when no longer needed.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="next_files_async" invoker="next_files_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + <parameter name="num_files" transfer-ownership="none"> + <doc xml:space="preserve">the number of file info objects to request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="next_files_finish" invoker="next_files_finish" throws="1"> + <doc xml:space="preserve">Finishes the asynchronous operation started with g_file_enumerator_next_files_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="FileInfo"/> + </type> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <method name="close" c:identifier="g_file_enumerator_close" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">#TRUE on success or #FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="close_async" c:identifier="g_file_enumerator_close_async"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="close_finish" c:identifier="g_file_enumerator_close_finish" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the close operation has finished successfully.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="get_child" c:identifier="g_file_enumerator_get_child" version="2.36"> + <doc xml:space="preserve">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); +]|</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile for the #GFileInfo passed it.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo gotten from g_file_enumerator_next_file() + or the async equivalents.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </parameter> + </parameters> + </method> + <method name="get_container" c:identifier="g_file_enumerator_get_container" version="2.18"> + <doc xml:space="preserve">Get the #GFile container which is being enumerated.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GFile which is being enumerated.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + </parameters> + </method> + <method name="has_pending" c:identifier="g_file_enumerator_has_pending"> + <doc xml:space="preserve">Checks if the file enumerator has pending operations.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @enumerator has pending operations.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_closed" c:identifier="g_file_enumerator_is_closed"> + <doc xml:space="preserve">Checks if the file enumerator has been closed.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @enumerator is closed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + </parameters> + </method> + <method name="iterate" c:identifier="g_file_enumerator_iterate" version="2.44" throws="1"> + <doc xml:space="preserve">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 +]|</doc> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="direnum" transfer-ownership="none"> + <doc xml:space="preserve">an open #GFileEnumerator</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + <parameter name="out_info" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">Output location for the next #GFileInfo, or %NULL</doc> + <type name="FileInfo" c:type="GFileInfo**"/> + </parameter> + <parameter name="out_child" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">Output location for the next #GFile, or %NULL</doc> + <type name="File" c:type="GFile**"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="next_file" c:identifier="g_file_enumerator_next_file" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">A #GFileInfo or %NULL on error + or end of enumerator. Free the returned object with + g_object_unref() when no longer needed.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="next_files_async" c:identifier="g_file_enumerator_next_files_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + <parameter name="num_files" transfer-ownership="none"> + <doc xml:space="preserve">the number of file info objects to request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="next_files_finish" c:identifier="g_file_enumerator_next_files_finish" throws="1"> + <doc xml:space="preserve">Finishes the asynchronous operation started with g_file_enumerator_next_files_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="FileInfo"/> + </type> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="set_pending" c:identifier="g_file_enumerator_set_pending"> + <doc xml:space="preserve">Sets the file enumerator as having pending operations.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </instance-parameter> + <parameter name="pending" transfer-ownership="none"> + <doc xml:space="preserve">a boolean value.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <property name="container" readable="0" writable="1" construct-only="1" transfer-ownership="none"> + <type name="File"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="FileEnumeratorPrivate" c:type="GFileEnumeratorPrivate*"/> + </field> + </class> + <record name="FileEnumeratorClass" c:type="GFileEnumeratorClass" glib:is-gtype-struct-for="FileEnumerator"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="next_file"> + <callback name="next_file" throws="1"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">A #GFileInfo or %NULL on error + or end of enumerator. Free the returned object with + g_object_unref() when no longer needed.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="close_fn"> + <callback name="close_fn" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="enumerator" transfer-ownership="none"> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="next_files_async"> + <callback name="next_files_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </parameter> + <parameter name="num_files" transfer-ownership="none"> + <doc xml:space="preserve">the number of file info objects to request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="next_files_finish"> + <callback name="next_files_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="FileInfo"/> + </type> + </return-value> + <parameters> + <parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="close_async"> + <callback name="close_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="close_finish"> + <callback name="close_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the close operation has finished successfully.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileEnumerator.</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved6" introspectable="0"> + <callback name="_g_reserved6"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved7" introspectable="0"> + <callback name="_g_reserved7"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="FileEnumeratorPrivate" c:type="GFileEnumeratorPrivate" disguised="1"/> + <class name="FileIOStream" c:symbol-prefix="file_io_stream" c:type="GFileIOStream" version="2.22" parent="IOStream" glib:type-name="GFileIOStream" glib:get-type="g_file_io_stream_get_type" glib:type-struct="FileIOStreamClass"> + <doc xml:space="preserve">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.</doc> + <implements name="Seekable"/> + <virtual-method name="can_seek"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="can_truncate"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_etag" invoker="get_etag" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the entity tag for the stream.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileIOStream.</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="query_info" invoker="query_info" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo for the @stream, or %NULL on error.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileIOStream.</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="query_info_async" invoker="query_info_async" version="2.22"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileIOStream.</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][gio-GIOScheduler] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="query_info_finish" invoker="query_info_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finalizes the asynchronous query started +by g_file_io_stream_query_info_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GFileInfo for the finished query.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileIOStream.</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="seek" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </instance-parameter> + <parameter name="offset" transfer-ownership="none"> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <type name="GLib.SeekType" c:type="GSeekType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="tell"> + <return-value transfer-ownership="none"> + <type name="gint64" c:type="goffset"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="truncate_fn" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </instance-parameter> + <parameter name="size" transfer-ownership="none"> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_etag" c:identifier="g_file_io_stream_get_etag" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the entity tag for the stream.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileIOStream.</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="query_info" c:identifier="g_file_io_stream_query_info" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo for the @stream, or %NULL on error.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileIOStream.</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="query_info_async" c:identifier="g_file_io_stream_query_info_async" version="2.22"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileIOStream.</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][gio-GIOScheduler] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="query_info_finish" c:identifier="g_file_io_stream_query_info_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finalizes the asynchronous query started +by g_file_io_stream_query_info_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GFileInfo for the finished query.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileIOStream.</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="IOStream" c:type="GIOStream"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="FileIOStreamPrivate" c:type="GFileIOStreamPrivate*"/> + </field> + </class> + <record name="FileIOStreamClass" c:type="GFileIOStreamClass" glib:is-gtype-struct-for="FileIOStream"> + <field name="parent_class"> + <type name="IOStreamClass" c:type="GIOStreamClass"/> + </field> + <field name="tell"> + <callback name="tell"> + <return-value transfer-ownership="none"> + <type name="gint64" c:type="goffset"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_seek"> + <callback name="can_seek"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="seek"> + <callback name="seek" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </parameter> + <parameter name="offset" transfer-ownership="none"> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <type name="GLib.SeekType" c:type="GSeekType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_truncate"> + <callback name="can_truncate"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="truncate_fn"> + <callback name="truncate_fn" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </parameter> + <parameter name="size" transfer-ownership="none"> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_info"> + <callback name="query_info" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo for the @stream, or %NULL on error.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileIOStream.</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_info_async"> + <callback name="query_info_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileIOStream.</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][gio-GIOScheduler] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_info_finish"> + <callback name="query_info_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GFileInfo for the finished query.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileIOStream.</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_etag"> + <callback name="get_etag"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the entity tag for the stream.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileIOStream.</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="FileIOStreamPrivate" c:type="GFileIOStreamPrivate" disguised="1"/> + <class name="FileIcon" c:symbol-prefix="file_icon" c:type="GFileIcon" parent="GObject.Object" glib:type-name="GFileIcon" glib:get-type="g_file_icon_get_type" glib:type-struct="FileIconClass"> + <doc xml:space="preserve">#GFileIcon specifies an icon by pointing to an image file +to be used as icon.</doc> + <implements name="Icon"/> + <implements name="LoadableIcon"/> + <constructor name="new" c:identifier="g_file_icon_new"> + <doc xml:space="preserve">Creates a new icon for a file.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon for the given + @file, or %NULL on error.</doc> + <type name="FileIcon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile.</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </constructor> + <method name="get_file" c:identifier="g_file_icon_get_file"> + <doc xml:space="preserve">Gets the #GFile associated with the given @icon.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GFile.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GIcon.</doc> + <type name="FileIcon" c:type="GFileIcon*"/> + </instance-parameter> + </parameters> + </method> + <property name="file" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The file containing the icon.</doc> + <type name="File"/> + </property> + </class> + <record name="FileIconClass" c:type="GFileIconClass" disguised="1" glib:is-gtype-struct-for="FileIcon"/> + <record name="FileIface" c:type="GFileIface" glib:is-gtype-struct-for="File"> + <doc xml:space="preserve">An interface for writing VFS file handles.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="dup"> + <callback name="dup"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile that is a duplicate + of the given #GFile.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="hash"> + <callback name="hash"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">#gconstpointer to a #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="equal"> + <callback name="equal"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @file1 and @file2 are equal.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file1" transfer-ownership="none"> + <doc xml:space="preserve">the first #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="file2" transfer-ownership="none"> + <doc xml:space="preserve">the second #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="is_native"> + <callback name="is_native"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @file is native</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="has_uri_scheme"> + <callback name="has_uri_scheme"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if #GFile's backend supports the + given URI scheme, %FALSE if URI scheme is %NULL, + not supported, or #GFile is invalid.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="uri_scheme" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a URI scheme</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_uri_scheme"> + <callback name="get_uri_scheme"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a string containing the URI scheme for the given + #GFile or %NULL if the #GFile was constructed with an invalid URI. The + returned string should be freed with g_free() when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_basename"> + <callback name="get_basename"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="filename" c:type="char*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_path"> + <callback name="get_path"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="filename" c:type="char*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_uri"> + <callback name="get_uri"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a string containing the #GFile's URI. If the #GFile was constructed + with an invalid URI, an invalid URI is returned. + The returned string should be freed with g_free() + when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_parse_name"> + <callback name="get_parse_name"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a string containing the #GFile's parse name. + The returned string should be freed with g_free() + when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_parent"> + <callback name="get_parent"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="prefix_matches"> + <callback name="prefix_matches"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @file's parent, grandparent, etc is @prefix, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="prefix" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_relative_path"> + <callback name="get_relative_path"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="filename" c:type="char*"/> + </return-value> + <parameters> + <parameter name="parent" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="descendant" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="resolve_relative_path"> + <callback name="resolve_relative_path"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFile to the resolved path. + %NULL if @relative_path is %NULL or if @file is invalid. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="relative_path" transfer-ownership="none"> + <doc xml:space="preserve">a given relative path string</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_child_for_display_name"> + <callback name="get_child_for_display_name" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile to the specified child, or + %NULL if the display name couldn't be converted. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="display_name" transfer-ownership="none"> + <doc xml:space="preserve">string to a possible child</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="enumerate_children"> + <callback name="enumerate_children" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GFileEnumerator if successful, + %NULL on error. Free the returned object with g_object_unref().</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="enumerate_children_async"> + <callback name="enumerate_children_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the + request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="enumerate_children_finish"> + <callback name="enumerate_children_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileEnumerator or %NULL + if an error occurred. + Free the returned object with g_object_unref().</doc> + <type name="FileEnumerator" c:type="GFileEnumerator*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_info"> + <callback name="query_info" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo for the given @file, or %NULL + on error. Free the returned object with g_object_unref().</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_info_async"> + <callback name="query_info_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the + request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_info_finish"> + <callback name="query_info_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFileInfo for given @file + or %NULL on error. Free the returned object with + g_object_unref().</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_filesystem_info"> + <callback name="query_filesystem_info" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo or %NULL if there was an error. + Free the returned object with g_object_unref().</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_filesystem_info_async"> + <callback name="query_filesystem_info_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">an attribute query string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_filesystem_info_finish"> + <callback name="query_filesystem_info_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFileInfo for given @file + or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="find_enclosing_mount"> + <callback name="find_enclosing_mount" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GMount where the @file is located + or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="Mount" c:type="GMount*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="find_enclosing_mount_async"> + <callback name="find_enclosing_mount_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="find_enclosing_mount_finish"> + <callback name="find_enclosing_mount_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GMount for given @file or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="Mount" c:type="GMount*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="set_display_name"> + <callback name="set_display_name" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile specifying what @file was renamed to, + or %NULL if there was an error. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="display_name" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="set_display_name_async"> + <callback name="set_display_name_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="display_name" transfer-ownership="none"> + <doc xml:space="preserve">a string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="set_display_name_finish"> + <callback name="set_display_name_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_settable_attributes"> + <callback name="query_settable_attributes" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileAttributeInfoList describing the settable attributes. + When you are done with it, release it with + g_file_attribute_info_list_unref()</doc> + <type name="FileAttributeInfoList" c:type="GFileAttributeInfoList*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_query_settable_attributes_async" introspectable="0"> + <callback name="_query_settable_attributes_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_query_settable_attributes_finish" introspectable="0"> + <callback name="_query_settable_attributes_finish"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="query_writable_namespaces"> + <callback name="query_writable_namespaces" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileAttributeInfoList describing the writable namespaces. + When you are done with it, release it with + g_file_attribute_info_list_unref()</doc> + <type name="FileAttributeInfoList" c:type="GFileAttributeInfoList*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_query_writable_namespaces_async" introspectable="0"> + <callback name="_query_writable_namespaces_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_query_writable_namespaces_finish" introspectable="0"> + <callback name="_query_writable_namespaces_finish"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="set_attribute"> + <callback name="set_attribute" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the attribute was set, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a string containing the attribute's name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">The type of the attribute</doc> + <type name="FileAttributeType" c:type="GFileAttributeType"/> + </parameter> + <parameter name="value_p" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to the value (or the pointer + itself if the type is a pointer type)</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="set_attributes_from_info"> + <callback name="set_attributes_from_info" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%FALSE if there was any error, %TRUE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">#GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="set_attributes_async"> + <callback name="set_attributes_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileQueryInfoFlags</doc> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">a #gpointer</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="set_attributes_finish"> + <callback name="set_attributes_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the attributes were set correctly, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="info" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo</doc> + <type name="FileInfo" c:type="GFileInfo**"/> + </parameter> + </parameters> + </callback> + </field> + <field name="read_fn"> + <callback name="read_fn" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFileInputStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">#GFile to read</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="read_async"> + <callback name="read_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="read_finish"> + <callback name="read_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInputStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="append_to"> + <callback name="append_to" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileOutputStream, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="append_to_async"> + <callback name="append_to_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="append_to_finish"> + <callback name="append_to_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a valid #GFileOutputStream + or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">#GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="create"> + <callback name="create" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileOutputStream for the newly created + file, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="create_async"> + <callback name="create_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="create_finish"> + <callback name="create_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileOutputStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="replace"> + <callback name="replace" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileOutputStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="etag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional [entity tag][gfile-etag] + for the current #GFile, or #NULL to ignore</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="make_backup" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a backup should be created</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="replace_async"> + <callback name="replace_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="etag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an [entity tag][gfile-etag] for the current #GFile, + or %NULL to ignore</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="make_backup" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a backup should be created</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="7"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="7"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="replace_finish"> + <callback name="replace_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileOutputStream, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="delete_file"> + <callback name="delete_file" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the file was deleted. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="delete_file_async"> + <callback name="delete_file_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="delete_file_finish"> + <callback name="delete_file_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the file was deleted. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="trash"> + <callback name="trash" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful trash, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">#GFile to send to trash</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="trash_async"> + <callback name="trash_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="trash_finish"> + <callback name="trash_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful trash, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="make_directory"> + <callback name="make_directory" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful creation, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="make_directory_async"> + <callback name="make_directory_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="make_directory_finish"> + <callback name="make_directory_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful directory creation, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="make_symbolic_link"> + <callback name="make_symbolic_link" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on the creation of a new symlink, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile with the name of the symlink to create</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="symlink_value" transfer-ownership="none"> + <doc xml:space="preserve">a string with the path for the target + of the new symlink</doc> + <type name="filename" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_make_symbolic_link_async" introspectable="0"> + <callback name="_make_symbolic_link_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_make_symbolic_link_finish" introspectable="0"> + <callback name="_make_symbolic_link_finish"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="copy"> + <callback name="copy" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="destination" transfer-ownership="none"> + <doc xml:space="preserve">destination #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">set of #GFileCopyFlags</doc> + <type name="FileCopyFlags" c:type="GFileCopyFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="progress_callback" transfer-ownership="none" nullable="1" allow-none="1" scope="call" closure="5"> + <doc xml:space="preserve">function to callback with + progress information, or %NULL if progress information is not needed</doc> + <type name="FileProgressCallback" c:type="GFileProgressCallback"/> + </parameter> + <parameter name="progress_callback_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to @progress_callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="copy_async"> + <callback name="copy_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="destination" transfer-ownership="none"> + <doc xml:space="preserve">destination #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">set of #GFileCopyFlags</doc> + <type name="FileCopyFlags" c:type="GFileCopyFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="progress_callback" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="6"> + <doc xml:space="preserve">function to callback with progress + information, or %NULL if progress information is not needed</doc> + <type name="FileProgressCallback" c:type="GFileProgressCallback"/> + </parameter> + <parameter name="progress_callback_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">user data to pass to @progress_callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="8"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="7"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="copy_finish"> + <callback name="copy_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a %TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="move"> + <callback name="move" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on successful move, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">#GFile pointing to the source location</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="destination" transfer-ownership="none"> + <doc xml:space="preserve">#GFile pointing to the destination location</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">set of #GFileCopyFlags</doc> + <type name="FileCopyFlags" c:type="GFileCopyFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="progress_callback" transfer-ownership="none" nullable="1" allow-none="1" scope="call" closure="5"> + <doc xml:space="preserve">#GFileProgressCallback + function for updates</doc> + <type name="FileProgressCallback" c:type="GFileProgressCallback"/> + </parameter> + <parameter name="progress_callback_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">gpointer to user data for + the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_move_async" introspectable="0"> + <callback name="_move_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_move_finish" introspectable="0"> + <callback name="_move_finish"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="mount_mountable"> + <callback name="mount_mountable"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountMountFlags" c:type="GMountMountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation, + or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="mount_mountable_finish"> + <callback name="mount_mountable_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="unmount_mountable"> + <callback name="unmount_mountable"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="unmount_mountable_finish"> + <callback name="unmount_mountable_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation finished successfully. + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject_mountable"> + <callback name="eject_mountable"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject_mountable_finish"> + <callback name="eject_mountable_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @file was ejected successfully. + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="mount_enclosing_volume"> + <callback name="mount_enclosing_volume"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="location" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountMountFlags" c:type="GMountMountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation + or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="mount_enclosing_volume_finish"> + <callback name="mount_enclosing_volume_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful. If an error has occurred, + this function will return %FALSE and set @error + appropriately if present.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="location" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="monitor_dir"> + <callback name="monitor_dir" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileMonitor for the given @file, + or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileMonitor" c:type="GFileMonitor*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileMonitorFlags</doc> + <type name="FileMonitorFlags" c:type="GFileMonitorFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="monitor_file"> + <callback name="monitor_file" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileMonitor for the given @file, + or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileMonitor" c:type="GFileMonitor*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileMonitorFlags</doc> + <type name="FileMonitorFlags" c:type="GFileMonitorFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="open_readwrite"> + <callback name="open_readwrite" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFileIOStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">#GFile to open</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="open_readwrite_async"> + <callback name="open_readwrite_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="open_readwrite_finish"> + <callback name="open_readwrite_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileIOStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="create_readwrite"> + <callback name="create_readwrite" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileIOStream for the newly created + file, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="create_readwrite_async"> + <callback name="create_readwrite_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="create_readwrite_finish"> + <callback name="create_readwrite_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileIOStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="replace_readwrite"> + <callback name="replace_readwrite" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileIOStream or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="etag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional [entity tag][gfile-etag] + for the current #GFile, or #NULL to ignore</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="make_backup" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a backup should be created</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="replace_readwrite_async"> + <callback name="replace_readwrite_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="etag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an [entity tag][gfile-etag] for the current #GFile, + or %NULL to ignore</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="make_backup" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a backup should be created</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileCreateFlags</doc> + <type name="FileCreateFlags" c:type="GFileCreateFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="7"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="7"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="replace_readwrite_finish"> + <callback name="replace_readwrite_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileIOStream, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="FileIOStream" c:type="GFileIOStream*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="start_mountable"> + <callback name="start_mountable"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="DriveStartFlags" c:type="GDriveStartFlags"/> + </parameter> + <parameter name="start_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation, or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="start_mountable_finish"> + <callback name="start_mountable_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation finished successfully. %FALSE +otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="stop_mountable"> + <callback name="stop_mountable"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation, + or %NULL to avoid user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="stop_mountable_finish"> + <callback name="stop_mountable_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation finished successfully. + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="supports_thread_contexts"> + <doc xml:space="preserve">a boolean that indicates whether the #GFile implementation supports thread-default contexts. Since 2.22.</doc> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="unmount_mountable_with_operation"> + <callback name="unmount_mountable_with_operation"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation, + or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="unmount_mountable_with_operation_finish"> + <callback name="unmount_mountable_with_operation_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation finished successfully. + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject_mountable_with_operation"> + <callback name="eject_mountable_with_operation"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation, + or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, + %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject_mountable_with_operation_finish"> + <callback name="eject_mountable_with_operation_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @file was ejected successfully. + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="poll_mountable"> + <callback name="poll_mountable"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="poll_mountable_finish"> + <callback name="poll_mountable_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation finished successfully. %FALSE +otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">input #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="measure_disk_usage" introspectable="0"> + <callback name="measure_disk_usage" introspectable="0" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful, with the out parameters set. + %FALSE otherwise, with @error set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">#GFileMeasureFlags</doc> + <type name="FileMeasureFlags" c:type="GFileMeasureFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="progress_callback" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">a #GFileMeasureProgressCallback</doc> + <type name="FileMeasureProgressCallback" c:type="GFileMeasureProgressCallback"/> + </parameter> + <parameter name="progress_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user_data for @progress_callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="disk_usage" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of bytes of disk space used</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="num_dirs" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of directories encountered</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="num_files" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of non-directories encountered</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="measure_disk_usage_async" introspectable="0"> + <callback name="measure_disk_usage_async" introspectable="0"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">#GFileMeasureFlags</doc> + <type name="FileMeasureFlags" c:type="GFileMeasureFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="progress_callback" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">a #GFileMeasureProgressCallback</doc> + <type name="FileMeasureProgressCallback" c:type="GFileMeasureProgressCallback"/> + </parameter> + <parameter name="progress_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user_data for @progress_callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="7"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when complete</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="7"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="measure_disk_usage_finish"> + <callback name="measure_disk_usage_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful, with the out parameters set. + %FALSE otherwise, with @error set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="disk_usage" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of bytes of disk space used</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="num_dirs" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of directories encountered</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="num_files" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the number of non-directories encountered</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="FileInfo" c:symbol-prefix="file_info" c:type="GFileInfo" parent="GObject.Object" glib:type-name="GFileInfo" glib:get-type="g_file_info_get_type" glib:type-struct="FileInfoClass"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_file_info_new"> + <doc xml:space="preserve">Creates a new file info structure.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + </constructor> + <method name="clear_status" c:identifier="g_file_info_clear_status"> + <doc xml:space="preserve">Clears the status information from @info.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="copy_into" c:identifier="g_file_info_copy_into"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="src_info" transfer-ownership="none"> + <doc xml:space="preserve">source to copy attributes from.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="dest_info" transfer-ownership="none"> + <doc xml:space="preserve">destination to copy attributes to.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </parameter> + </parameters> + </method> + <method name="dup" c:identifier="g_file_info_dup"> + <doc xml:space="preserve">Duplicates a file info structure.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a duplicate #GFileInfo of @other.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="other" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_attribute_as_string" c:identifier="g_file_info_get_attribute_as_string"> + <doc xml:space="preserve">Gets the value of a attribute, formatted as a string. +This escapes things as needed to make the string valid +UTF-8.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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().</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_attribute_boolean" c:identifier="g_file_info_get_attribute_boolean"> + <doc xml:space="preserve">Gets the value of a boolean attribute. If the attribute does not +contain a boolean value, %FALSE will be returned.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the boolean value contained within the attribute.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_attribute_byte_string" c:identifier="g_file_info_get_attribute_byte_string"> + <doc xml:space="preserve">Gets the value of a byte string attribute. If the attribute does +not contain a byte string, %NULL will be returned.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the contents of the @attribute value as a byte string, or +%NULL otherwise.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_attribute_data" c:identifier="g_file_info_get_attribute_data"> + <doc xml:space="preserve">Gets the attribute type, value and status for an attribute key.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @info has an attribute named @attribute, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="type" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the attribute type, or %NULL</doc> + <type name="FileAttributeType" c:type="GFileAttributeType*"/> + </parameter> + <parameter name="value_pp" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the + attribute value, or %NULL; the attribute value will not be %NULL</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + <parameter name="status" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the attribute status, or %NULL</doc> + <type name="FileAttributeStatus" c:type="GFileAttributeStatus*"/> + </parameter> + </parameters> + </method> + <method name="get_attribute_int32" c:identifier="g_file_info_get_attribute_int32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a signed 32-bit integer from the attribute.</doc> + <type name="gint32" c:type="gint32"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_attribute_int64" c:identifier="g_file_info_get_attribute_int64"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a signed 64-bit integer from the attribute.</doc> + <type name="gint64" c:type="gint64"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_attribute_object" c:identifier="g_file_info_get_attribute_object"> + <doc xml:space="preserve">Gets the value of a #GObject attribute. If the attribute does +not contain a #GObject, %NULL will be returned.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a #GObject associated with the given @attribute, +or %NULL otherwise.</doc> + <type name="GObject.Object" c:type="GObject*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_attribute_status" c:identifier="g_file_info_get_attribute_status"> + <doc xml:space="preserve">Gets the attribute status for an attribute key.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GFileAttributeStatus for the given @attribute, or + %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid.</doc> + <type name="FileAttributeStatus" c:type="GFileAttributeStatus"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_attribute_string" c:identifier="g_file_info_get_attribute_string"> + <doc xml:space="preserve">Gets the value of a string attribute. If the attribute does +not contain a string, %NULL will be returned.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the contents of the @attribute value as a UTF-8 string, +or %NULL otherwise.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_attribute_stringv" c:identifier="g_file_info_get_attribute_stringv" version="2.22"> + <doc xml:space="preserve">Gets the value of a stringv attribute. If the attribute does +not contain a stringv, %NULL will be returned.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the contents of the @attribute value as a stringv, +or %NULL otherwise. Do not free. These returned strings are UTF-8.</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_attribute_type" c:identifier="g_file_info_get_attribute_type"> + <doc xml:space="preserve">Gets the attribute type for an attribute key.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GFileAttributeType for the given @attribute, or +%G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set.</doc> + <type name="FileAttributeType" c:type="GFileAttributeType"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_attribute_uint32" c:identifier="g_file_info_get_attribute_uint32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an unsigned 32-bit integer from the attribute.</doc> + <type name="guint32" c:type="guint32"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_attribute_uint64" c:identifier="g_file_info_get_attribute_uint64"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a unsigned 64-bit integer from the attribute.</doc> + <type name="guint64" c:type="guint64"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_content_type" c:identifier="g_file_info_get_content_type"> + <doc xml:space="preserve">Gets the file's content type.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing the file's content type, +or %NULL if unknown.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_deletion_date" c:identifier="g_file_info_get_deletion_date" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GDateTime, or %NULL.</doc> + <type name="GLib.DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_display_name" c:identifier="g_file_info_get_display_name"> + <doc xml:space="preserve">Gets a display name for a file. This is guaranteed to always be set.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a string containing the display name.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_edit_name" c:identifier="g_file_info_get_edit_name"> + <doc xml:space="preserve">Gets the edit name for a file.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a string containing the edit name.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_etag" c:identifier="g_file_info_get_etag"> + <doc xml:space="preserve">Gets the [entity tag][gfile-etag] for a given +#GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing the value of the "etag:value" attribute.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_file_type" c:identifier="g_file_info_get_file_type"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GFileType for the given file.</doc> + <type name="FileType" c:type="GFileType"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_icon" c:identifier="g_file_info_get_icon"> + <doc xml:space="preserve">Gets the icon for a file.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">#GIcon for the given @info.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_backup" c:identifier="g_file_info_get_is_backup"> + <doc xml:space="preserve">Checks if a file is a backup file.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if file is a backup file, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_hidden" c:identifier="g_file_info_get_is_hidden"> + <doc xml:space="preserve">Checks if a file is hidden.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the file is a hidden file, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_symlink" c:identifier="g_file_info_get_is_symlink"> + <doc xml:space="preserve">Checks if a file is a symlink.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the given @info is a symlink.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_modification_date_time" c:identifier="g_file_info_get_modification_date_time" version="2.62"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">modification time, or %NULL if unknown</doc> + <type name="GLib.DateTime" c:type="GDateTime*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_modification_time" c:identifier="g_file_info_get_modification_time" deprecated="1" deprecated-version="2.62"> + <doc xml:space="preserve">Gets the modification time of the current @info and sets it +in @result.</doc> + <doc-deprecated xml:space="preserve">Use g_file_info_get_modification_date_time() instead, as + #GTimeVal is deprecated due to the year 2038 problem.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="result" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeVal.</doc> + <type name="GLib.TimeVal" c:type="GTimeVal*"/> + </parameter> + </parameters> + </method> + <method name="get_name" c:identifier="g_file_info_get_name"> + <doc xml:space="preserve">Gets the name for a file. This is guaranteed to always be set.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a string containing the file name.</doc> + <type name="filename" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_size" c:identifier="g_file_info_get_size"> + <doc xml:space="preserve">Gets the file's size (in bytes). The size is retrieved through the value of +the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute and is converted +from #guint64 to #goffset before returning the result.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #goffset containing the file's size (in bytes).</doc> + <type name="gint64" c:type="goffset"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_sort_order" c:identifier="g_file_info_get_sort_order"> + <doc xml:space="preserve">Gets the value of the sort_order attribute from the #GFileInfo. +See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #gint32 containing the value of the "standard::sort_order" attribute.</doc> + <type name="gint32" c:type="gint32"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_symbolic_icon" c:identifier="g_file_info_get_symbolic_icon" version="2.34"> + <doc xml:space="preserve">Gets the symbolic icon for a file.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">#GIcon for the given @info.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_symlink_target" c:identifier="g_file_info_get_symlink_target"> + <doc xml:space="preserve">Gets the symlink target for a given #GFileInfo.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing the symlink target.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + <method name="has_attribute" c:identifier="g_file_info_has_attribute"> + <doc xml:space="preserve">Checks if a file info structure has an attribute named @attribute.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @info has an attribute named @attribute, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="has_namespace" c:identifier="g_file_info_has_namespace" version="2.22"> + <doc xml:space="preserve">Checks if a file info structure has an attribute in the +specified @name_space.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @info has an attribute in @name_space, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="name_space" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute namespace.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="list_attributes" c:identifier="g_file_info_list_attributes"> + <doc xml:space="preserve">Lists the file info structure's attributes.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a +null-terminated array of strings of all of the possible attribute +types for the given @name_space, or %NULL on error.</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="name_space" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a file attribute key's namespace, or %NULL to list + all attributes.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="remove_attribute" c:identifier="g_file_info_remove_attribute"> + <doc xml:space="preserve">Removes all cases of @attribute from @info if it exists.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_attribute" c:identifier="g_file_info_set_attribute"> + <doc xml:space="preserve">Sets the @attribute to contain the given value, if possible. To unset the +attribute, use %G_FILE_ATTRIBUTE_TYPE_INVALID for @type.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileAttributeType</doc> + <type name="FileAttributeType" c:type="GFileAttributeType"/> + </parameter> + <parameter name="value_p" transfer-ownership="none"> + <doc xml:space="preserve">pointer to the value</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="set_attribute_boolean" c:identifier="g_file_info_set_attribute_boolean"> + <doc xml:space="preserve">Sets the @attribute to contain the given @attr_value, +if possible.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="attr_value" transfer-ownership="none"> + <doc xml:space="preserve">a boolean value.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_attribute_byte_string" c:identifier="g_file_info_set_attribute_byte_string"> + <doc xml:space="preserve">Sets the @attribute to contain the given @attr_value, +if possible.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="attr_value" transfer-ownership="none"> + <doc xml:space="preserve">a byte string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_attribute_int32" c:identifier="g_file_info_set_attribute_int32"> + <doc xml:space="preserve">Sets the @attribute to contain the given @attr_value, +if possible.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="attr_value" transfer-ownership="none"> + <doc xml:space="preserve">a signed 32-bit integer</doc> + <type name="gint32" c:type="gint32"/> + </parameter> + </parameters> + </method> + <method name="set_attribute_int64" c:identifier="g_file_info_set_attribute_int64"> + <doc xml:space="preserve">Sets the @attribute to contain the given @attr_value, +if possible.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">attribute name to set.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="attr_value" transfer-ownership="none"> + <doc xml:space="preserve">int64 value to set attribute to.</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + </parameters> + </method> + <method name="set_attribute_mask" c:identifier="g_file_info_set_attribute_mask"> + <doc xml:space="preserve">Sets @mask on @info to match specific attribute types.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="mask" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileAttributeMatcher.</doc> + <type name="FileAttributeMatcher" c:type="GFileAttributeMatcher*"/> + </parameter> + </parameters> + </method> + <method name="set_attribute_object" c:identifier="g_file_info_set_attribute_object"> + <doc xml:space="preserve">Sets the @attribute to contain the given @attr_value, +if possible.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="attr_value" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject.</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + </parameters> + </method> + <method name="set_attribute_status" c:identifier="g_file_info_set_attribute_status" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the status was changed, %FALSE if the key was not set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="status" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileAttributeStatus</doc> + <type name="FileAttributeStatus" c:type="GFileAttributeStatus"/> + </parameter> + </parameters> + </method> + <method name="set_attribute_string" c:identifier="g_file_info_set_attribute_string"> + <doc xml:space="preserve">Sets the @attribute to contain the given @attr_value, +if possible.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="attr_value" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_attribute_stringv" c:identifier="g_file_info_set_attribute_stringv"> + <doc xml:space="preserve">Sets the @attribute to contain the given @attr_value, +if possible. + +Sinze: 2.22</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="attr_value" transfer-ownership="none"> + <doc xml:space="preserve">a %NULL + terminated array of UTF-8 strings.</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </parameter> + </parameters> + </method> + <method name="set_attribute_uint32" c:identifier="g_file_info_set_attribute_uint32"> + <doc xml:space="preserve">Sets the @attribute to contain the given @attr_value, +if possible.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="attr_value" transfer-ownership="none"> + <doc xml:space="preserve">an unsigned 32-bit integer.</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + </parameters> + </method> + <method name="set_attribute_uint64" c:identifier="g_file_info_set_attribute_uint64"> + <doc xml:space="preserve">Sets the @attribute to contain the given @attr_value, +if possible.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute key.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="attr_value" transfer-ownership="none"> + <doc xml:space="preserve">an unsigned 64-bit integer.</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + </parameters> + </method> + <method name="set_content_type" c:identifier="g_file_info_set_content_type"> + <doc xml:space="preserve">Sets the content type attribute for a given #GFileInfo. +See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">a content type. See [GContentType][gio-GContentType]</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_display_name" c:identifier="g_file_info_set_display_name"> + <doc xml:space="preserve">Sets the display name for the current #GFileInfo. +See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="display_name" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a display name.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_edit_name" c:identifier="g_file_info_set_edit_name"> + <doc xml:space="preserve">Sets the edit name for the current file. +See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="edit_name" transfer-ownership="none"> + <doc xml:space="preserve">a string containing an edit name.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_file_type" c:identifier="g_file_info_set_file_type"> + <doc xml:space="preserve">Sets the file type in a #GFileInfo to @type. +See %G_FILE_ATTRIBUTE_STANDARD_TYPE.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileType.</doc> + <type name="FileType" c:type="GFileType"/> + </parameter> + </parameters> + </method> + <method name="set_icon" c:identifier="g_file_info_set_icon"> + <doc xml:space="preserve">Sets the icon for a given #GFileInfo. +See %G_FILE_ATTRIBUTE_STANDARD_ICON.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GIcon.</doc> + <type name="Icon" c:type="GIcon*"/> + </parameter> + </parameters> + </method> + <method name="set_is_hidden" c:identifier="g_file_info_set_is_hidden"> + <doc xml:space="preserve">Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden. +See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="is_hidden" transfer-ownership="none"> + <doc xml:space="preserve">a #gboolean.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_is_symlink" c:identifier="g_file_info_set_is_symlink"> + <doc xml:space="preserve">Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink. +See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="is_symlink" transfer-ownership="none"> + <doc xml:space="preserve">a #gboolean.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_modification_date_time" c:identifier="g_file_info_set_modification_date_time" version="2.62"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="mtime" transfer-ownership="none"> + <doc xml:space="preserve">a #GDateTime.</doc> + <type name="GLib.DateTime" c:type="GDateTime*"/> + </parameter> + </parameters> + </method> + <method name="set_modification_time" c:identifier="g_file_info_set_modification_time" deprecated="1" deprecated-version="2.62"> + <doc xml:space="preserve">Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and +%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the +given time value.</doc> + <doc-deprecated xml:space="preserve">Use g_file_info_set_modification_date_time() instead, as + #GTimeVal is deprecated due to the year 2038 problem.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="mtime" transfer-ownership="none"> + <doc xml:space="preserve">a #GTimeVal.</doc> + <type name="GLib.TimeVal" c:type="GTimeVal*"/> + </parameter> + </parameters> + </method> + <method name="set_name" c:identifier="g_file_info_set_name"> + <doc xml:space="preserve">Sets the name attribute for the current #GFileInfo. +See %G_FILE_ATTRIBUTE_STANDARD_NAME.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a name.</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_size" c:identifier="g_file_info_set_size"> + <doc xml:space="preserve">Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info +to the given size.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">a #goffset containing the file's size.</doc> + <type name="gint64" c:type="goffset"/> + </parameter> + </parameters> + </method> + <method name="set_sort_order" c:identifier="g_file_info_set_sort_order"> + <doc xml:space="preserve">Sets the sort order attribute in the file info structure. See +%G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="sort_order" transfer-ownership="none"> + <doc xml:space="preserve">a sort order integer.</doc> + <type name="gint32" c:type="gint32"/> + </parameter> + </parameters> + </method> + <method name="set_symbolic_icon" c:identifier="g_file_info_set_symbolic_icon" version="2.34"> + <doc xml:space="preserve">Sets the symbolic icon for a given #GFileInfo. +See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GIcon.</doc> + <type name="Icon" c:type="GIcon*"/> + </parameter> + </parameters> + </method> + <method name="set_symlink_target" c:identifier="g_file_info_set_symlink_target"> + <doc xml:space="preserve">Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info +to the given symlink target.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + <parameter name="symlink_target" transfer-ownership="none"> + <doc xml:space="preserve">a static string containing a path to a symlink target.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="unset_attribute_mask" c:identifier="g_file_info_unset_attribute_mask"> + <doc xml:space="preserve">Unsets a mask set by g_file_info_set_attribute_mask(), if one +is set.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="info" transfer-ownership="none"> + <doc xml:space="preserve">#GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </instance-parameter> + </parameters> + </method> + </class> + <record name="FileInfoClass" c:type="GFileInfoClass" disguised="1" glib:is-gtype-struct-for="FileInfo"/> + <class name="FileInputStream" c:symbol-prefix="file_input_stream" c:type="GFileInputStream" parent="InputStream" glib:type-name="GFileInputStream" glib:get-type="g_file_input_stream_get_type" glib:type-struct="FileInputStreamClass"> + <doc xml:space="preserve">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().</doc> + <implements name="Seekable"/> + <virtual-method name="can_seek"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="query_info" invoker="query_info" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo, or %NULL on error.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInputStream.</doc> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="query_info_async" invoker="query_info_async"> + <doc xml:space="preserve">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</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInputStream.</doc> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="query_info_finish" invoker="query_info_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous info query operation.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInputStream.</doc> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="seek" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </instance-parameter> + <parameter name="offset" transfer-ownership="none"> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <type name="GLib.SeekType" c:type="GSeekType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="tell"> + <return-value transfer-ownership="none"> + <type name="gint64" c:type="goffset"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="query_info" c:identifier="g_file_input_stream_query_info" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo, or %NULL on error.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInputStream.</doc> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="query_info_async" c:identifier="g_file_input_stream_query_info_async"> + <doc xml:space="preserve">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</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInputStream.</doc> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="query_info_finish" c:identifier="g_file_input_stream_query_info_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous info query operation.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInputStream.</doc> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="InputStream" c:type="GInputStream"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="FileInputStreamPrivate" c:type="GFileInputStreamPrivate*"/> + </field> + </class> + <record name="FileInputStreamClass" c:type="GFileInputStreamClass" glib:is-gtype-struct-for="FileInputStream"> + <field name="parent_class"> + <type name="InputStreamClass" c:type="GInputStreamClass"/> + </field> + <field name="tell"> + <callback name="tell"> + <return-value transfer-ownership="none"> + <type name="gint64" c:type="goffset"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_seek"> + <callback name="can_seek"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="seek"> + <callback name="seek" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </parameter> + <parameter name="offset" transfer-ownership="none"> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <type name="GLib.SeekType" c:type="GSeekType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_info"> + <callback name="query_info" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo, or %NULL on error.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInputStream.</doc> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_info_async"> + <callback name="query_info_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInputStream.</doc> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_info_finish"> + <callback name="query_info_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GFileInfo.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileInputStream.</doc> + <type name="FileInputStream" c:type="GFileInputStream*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="FileInputStreamPrivate" c:type="GFileInputStreamPrivate" disguised="1"/> + <bitfield name="FileMeasureFlags" version="2.38" glib:type-name="GFileMeasureFlags" glib:get-type="g_file_measure_flags_get_type" c:type="GFileMeasureFlags"> + <doc xml:space="preserve">Flags that can be used with g_file_measure_disk_usage().</doc> + <member name="none" value="0" c:identifier="G_FILE_MEASURE_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="report_any_error" value="2" c:identifier="G_FILE_MEASURE_REPORT_ANY_ERROR" glib:nick="report-any-error"> + <doc xml:space="preserve">Report any error encountered + while traversing the directory tree. Normally errors are only + reported for the toplevel file.</doc> + </member> + <member name="apparent_size" value="4" c:identifier="G_FILE_MEASURE_APPARENT_SIZE" glib:nick="apparent-size"> + <doc xml:space="preserve">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`.</doc> + </member> + <member name="no_xdev" value="8" c:identifier="G_FILE_MEASURE_NO_XDEV" glib:nick="no-xdev"> + <doc xml:space="preserve">Do not cross mount point boundaries. + Compare with `du -x`.</doc> + </member> + </bitfield> + <callback name="FileMeasureProgressCallback" c:type="GFileMeasureProgressCallback" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="reporting" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if more reports will come</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="current_size" transfer-ownership="none"> + <doc xml:space="preserve">the current cumulative size measurement</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="num_dirs" transfer-ownership="none"> + <doc xml:space="preserve">the number of directories visited so far</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="num_files" transfer-ownership="none"> + <doc xml:space="preserve">the number of non-directory files encountered</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data passed to the original request for this callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <class name="FileMonitor" c:symbol-prefix="file_monitor" c:type="GFileMonitor" parent="GObject.Object" abstract="1" glib:type-name="GFileMonitor" glib:get-type="g_file_monitor_get_type" glib:type-struct="FileMonitorClass"> + <doc xml:space="preserve">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).</doc> + <virtual-method name="cancel" invoker="cancel"> + <doc xml:space="preserve">Cancels a file monitor.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">always %TRUE</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileMonitor.</doc> + <type name="FileMonitor" c:type="GFileMonitor*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <type name="FileMonitor" c:type="GFileMonitor*"/> + </instance-parameter> + <parameter name="file" transfer-ownership="none"> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="other_file" transfer-ownership="none"> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="event_type" transfer-ownership="none"> + <type name="FileMonitorEvent" c:type="GFileMonitorEvent"/> + </parameter> + </parameters> + </virtual-method> + <method name="cancel" c:identifier="g_file_monitor_cancel"> + <doc xml:space="preserve">Cancels a file monitor.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">always %TRUE</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileMonitor.</doc> + <type name="FileMonitor" c:type="GFileMonitor*"/> + </instance-parameter> + </parameters> + </method> + <method name="emit_event" c:identifier="g_file_monitor_emit_event"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileMonitor.</doc> + <type name="FileMonitor" c:type="GFileMonitor*"/> + </instance-parameter> + <parameter name="child" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile.</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="other_file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile.</doc> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="event_type" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GFileMonitorEvent flags.</doc> + <type name="FileMonitorEvent" c:type="GFileMonitorEvent"/> + </parameter> + </parameters> + </method> + <method name="is_cancelled" c:identifier="g_file_monitor_is_cancelled"> + <doc xml:space="preserve">Returns whether the monitor is canceled.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if monitor is canceled. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileMonitor</doc> + <type name="FileMonitor" c:type="GFileMonitor*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_rate_limit" c:identifier="g_file_monitor_set_rate_limit"> + <doc xml:space="preserve">Sets the rate limit to which the @monitor will report +consecutive change events to the same file.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileMonitor.</doc> + <type name="FileMonitor" c:type="GFileMonitor*"/> + </instance-parameter> + <parameter name="limit_msecs" transfer-ownership="none"> + <doc xml:space="preserve">a non-negative integer with the limit in milliseconds + to poll for changes</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <property name="cancelled" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="rate-limit" writable="1" transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="FileMonitorPrivate" c:type="GFileMonitorPrivate*"/> + </field> + <glib:signal name="changed" when="last"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">a #GFile.</doc> + <type name="File"/> + </parameter> + <parameter name="other_file" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GFile or #NULL.</doc> + <type name="File"/> + </parameter> + <parameter name="event_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileMonitorEvent.</doc> + <type name="FileMonitorEvent"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="FileMonitorClass" c:type="GFileMonitorClass" glib:is-gtype-struct-for="FileMonitor"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="changed"> + <callback name="changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="monitor" transfer-ownership="none"> + <type name="FileMonitor" c:type="GFileMonitor*"/> + </parameter> + <parameter name="file" transfer-ownership="none"> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="other_file" transfer-ownership="none"> + <type name="File" c:type="GFile*"/> + </parameter> + <parameter name="event_type" transfer-ownership="none"> + <type name="FileMonitorEvent" c:type="GFileMonitorEvent"/> + </parameter> + </parameters> + </callback> + </field> + <field name="cancel"> + <callback name="cancel"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">always %TRUE</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileMonitor.</doc> + <type name="FileMonitor" c:type="GFileMonitor*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <enumeration name="FileMonitorEvent" glib:type-name="GFileMonitorEvent" glib:get-type="g_file_monitor_event_get_type" c:type="GFileMonitorEvent"> + <doc xml:space="preserve">Specifies what type of event a monitor event is.</doc> + <member name="changed" value="0" c:identifier="G_FILE_MONITOR_EVENT_CHANGED" glib:nick="changed"> + <doc xml:space="preserve">a file changed.</doc> + </member> + <member name="changes_done_hint" value="1" c:identifier="G_FILE_MONITOR_EVENT_CHANGES_DONE_HINT" glib:nick="changes-done-hint"> + <doc xml:space="preserve">a hint that this was probably the last change in a set of changes.</doc> + </member> + <member name="deleted" value="2" c:identifier="G_FILE_MONITOR_EVENT_DELETED" glib:nick="deleted"> + <doc xml:space="preserve">a file was deleted.</doc> + </member> + <member name="created" value="3" c:identifier="G_FILE_MONITOR_EVENT_CREATED" glib:nick="created"> + <doc xml:space="preserve">a file was created.</doc> + </member> + <member name="attribute_changed" value="4" c:identifier="G_FILE_MONITOR_EVENT_ATTRIBUTE_CHANGED" glib:nick="attribute-changed"> + <doc xml:space="preserve">a file attribute was changed.</doc> + </member> + <member name="pre_unmount" value="5" c:identifier="G_FILE_MONITOR_EVENT_PRE_UNMOUNT" glib:nick="pre-unmount"> + <doc xml:space="preserve">the file location will soon be unmounted.</doc> + </member> + <member name="unmounted" value="6" c:identifier="G_FILE_MONITOR_EVENT_UNMOUNTED" glib:nick="unmounted"> + <doc xml:space="preserve">the file location was unmounted.</doc> + </member> + <member name="moved" value="7" c:identifier="G_FILE_MONITOR_EVENT_MOVED" glib:nick="moved"> + <doc xml:space="preserve">the file was moved -- only sent if the + (deprecated) %G_FILE_MONITOR_SEND_MOVED flag is set</doc> + </member> + <member name="renamed" value="8" c:identifier="G_FILE_MONITOR_EVENT_RENAMED" glib:nick="renamed"> + <doc xml:space="preserve">the file was renamed within the + current directory -- only sent if the %G_FILE_MONITOR_WATCH_MOVES + flag is set. Since: 2.46.</doc> + </member> + <member name="moved_in" value="9" c:identifier="G_FILE_MONITOR_EVENT_MOVED_IN" glib:nick="moved-in"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="moved_out" value="10" c:identifier="G_FILE_MONITOR_EVENT_MOVED_OUT" glib:nick="moved-out"> + <doc xml:space="preserve">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</doc> + </member> + </enumeration> + <bitfield name="FileMonitorFlags" glib:type-name="GFileMonitorFlags" glib:get-type="g_file_monitor_flags_get_type" c:type="GFileMonitorFlags"> + <doc xml:space="preserve">Flags used to set what a #GFileMonitor will watch for.</doc> + <member name="none" value="0" c:identifier="G_FILE_MONITOR_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="watch_mounts" value="1" c:identifier="G_FILE_MONITOR_WATCH_MOUNTS" glib:nick="watch-mounts"> + <doc xml:space="preserve">Watch for mount events.</doc> + </member> + <member name="send_moved" value="2" c:identifier="G_FILE_MONITOR_SEND_MOVED" glib:nick="send-moved"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="watch_hard_links" value="4" c:identifier="G_FILE_MONITOR_WATCH_HARD_LINKS" glib:nick="watch-hard-links"> + <doc xml:space="preserve">Watch for changes to the file made + via another hard link. Since 2.36.</doc> + </member> + <member name="watch_moves" value="8" c:identifier="G_FILE_MONITOR_WATCH_MOVES" glib:nick="watch-moves"> + <doc xml:space="preserve">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.</doc> + </member> + </bitfield> + <record name="FileMonitorPrivate" c:type="GFileMonitorPrivate" disguised="1"/> + <class name="FileOutputStream" c:symbol-prefix="file_output_stream" c:type="GFileOutputStream" parent="OutputStream" glib:type-name="GFileOutputStream" glib:get-type="g_file_output_stream_get_type" glib:type-struct="FileOutputStreamClass"> + <doc xml:space="preserve">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().</doc> + <implements name="Seekable"/> + <virtual-method name="can_seek"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="can_truncate"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_etag" invoker="get_etag"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the entity tag for the stream.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileOutputStream.</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="query_info" invoker="query_info" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo for the @stream, or %NULL on error.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileOutputStream.</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="query_info_async" invoker="query_info_async"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileOutputStream.</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][gio-GIOScheduler] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="query_info_finish" invoker="query_info_finish" throws="1"> + <doc xml:space="preserve">Finalizes the asynchronous query started +by g_file_output_stream_query_info_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GFileInfo for the finished query.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileOutputStream.</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="seek" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </instance-parameter> + <parameter name="offset" transfer-ownership="none"> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <type name="GLib.SeekType" c:type="GSeekType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="tell"> + <return-value transfer-ownership="none"> + <type name="gint64" c:type="goffset"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="truncate_fn" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </instance-parameter> + <parameter name="size" transfer-ownership="none"> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_etag" c:identifier="g_file_output_stream_get_etag"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the entity tag for the stream.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileOutputStream.</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="query_info" c:identifier="g_file_output_stream_query_info" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo for the @stream, or %NULL on error.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileOutputStream.</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="query_info_async" c:identifier="g_file_output_stream_query_info_async"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileOutputStream.</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </instance-parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][gio-GIOScheduler] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="query_info_finish" c:identifier="g_file_output_stream_query_info_finish" throws="1"> + <doc xml:space="preserve">Finalizes the asynchronous query started +by g_file_output_stream_query_info_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GFileInfo for the finished query.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileOutputStream.</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="OutputStream" c:type="GOutputStream"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="FileOutputStreamPrivate" c:type="GFileOutputStreamPrivate*"/> + </field> + </class> + <record name="FileOutputStreamClass" c:type="GFileOutputStreamClass" glib:is-gtype-struct-for="FileOutputStream"> + <field name="parent_class"> + <type name="OutputStreamClass" c:type="GOutputStreamClass"/> + </field> + <field name="tell"> + <callback name="tell"> + <return-value transfer-ownership="none"> + <type name="gint64" c:type="goffset"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_seek"> + <callback name="can_seek"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="seek"> + <callback name="seek" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </parameter> + <parameter name="offset" transfer-ownership="none"> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <type name="GLib.SeekType" c:type="GSeekType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_truncate"> + <callback name="can_truncate"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="truncate_fn"> + <callback name="truncate_fn" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </parameter> + <parameter name="size" transfer-ownership="none"> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_info"> + <callback name="query_info" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFileInfo for the @stream, or %NULL on error.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileOutputStream.</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_info_async"> + <callback name="query_info_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileOutputStream.</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </parameter> + <parameter name="attributes" transfer-ownership="none"> + <doc xml:space="preserve">a file attribute query string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][gio-GIOScheduler] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="query_info_finish"> + <callback name="query_info_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GFileInfo for the finished query.</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileOutputStream.</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_etag"> + <callback name="get_etag"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the entity tag for the stream.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFileOutputStream.</doc> + <type name="FileOutputStream" c:type="GFileOutputStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="FileOutputStreamPrivate" c:type="GFileOutputStreamPrivate" disguised="1"/> + <callback name="FileProgressCallback" c:type="GFileProgressCallback"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="current_num_bytes" transfer-ownership="none"> + <doc xml:space="preserve">the current number of bytes in the operation.</doc> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="total_num_bytes" transfer-ownership="none"> + <doc xml:space="preserve">the total number of bytes in the operation.</doc> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">user data passed to the callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <bitfield name="FileQueryInfoFlags" glib:type-name="GFileQueryInfoFlags" glib:get-type="g_file_query_info_flags_get_type" c:type="GFileQueryInfoFlags"> + <doc xml:space="preserve">Flags used when querying a #GFileInfo.</doc> + <member name="none" value="0" c:identifier="G_FILE_QUERY_INFO_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="nofollow_symlinks" value="1" c:identifier="G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS" glib:nick="nofollow-symlinks"> + <doc xml:space="preserve">Don't follow symlinks.</doc> + </member> + </bitfield> + <callback name="FileReadMoreCallback" c:type="GFileReadMoreCallback"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if more data should be read back. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file_contents" transfer-ownership="none"> + <doc xml:space="preserve">the data as currently read.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="file_size" transfer-ownership="none"> + <doc xml:space="preserve">the size of the data currently read.</doc> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="callback_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">data passed to the callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <enumeration name="FileType" glib:type-name="GFileType" glib:get-type="g_file_type_get_type" c:type="GFileType"> + <doc xml:space="preserve">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.</doc> + <member name="unknown" value="0" c:identifier="G_FILE_TYPE_UNKNOWN" glib:nick="unknown"> + <doc xml:space="preserve">File's type is unknown.</doc> + </member> + <member name="regular" value="1" c:identifier="G_FILE_TYPE_REGULAR" glib:nick="regular"> + <doc xml:space="preserve">File handle represents a regular file.</doc> + </member> + <member name="directory" value="2" c:identifier="G_FILE_TYPE_DIRECTORY" glib:nick="directory"> + <doc xml:space="preserve">File handle represents a directory.</doc> + </member> + <member name="symbolic_link" value="3" c:identifier="G_FILE_TYPE_SYMBOLIC_LINK" glib:nick="symbolic-link"> + <doc xml:space="preserve">File handle represents a symbolic link + (Unix systems).</doc> + </member> + <member name="special" value="4" c:identifier="G_FILE_TYPE_SPECIAL" glib:nick="special"> + <doc xml:space="preserve">File is a "special" file, such as a socket, fifo, + block device, or character device.</doc> + </member> + <member name="shortcut" value="5" c:identifier="G_FILE_TYPE_SHORTCUT" glib:nick="shortcut"> + <doc xml:space="preserve">File is a shortcut (Windows systems).</doc> + </member> + <member name="mountable" value="6" c:identifier="G_FILE_TYPE_MOUNTABLE" glib:nick="mountable"> + <doc xml:space="preserve">File is a mountable location.</doc> + </member> + </enumeration> + <class name="FilenameCompleter" c:symbol-prefix="filename_completer" c:type="GFilenameCompleter" parent="GObject.Object" glib:type-name="GFilenameCompleter" glib:get-type="g_filename_completer_get_type" glib:type-struct="FilenameCompleterClass"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_filename_completer_new"> + <doc xml:space="preserve">Creates a new filename completer.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFilenameCompleter.</doc> + <type name="FilenameCompleter" c:type="GFilenameCompleter*"/> + </return-value> + </constructor> + <virtual-method name="got_completion_data"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="filename_completer" transfer-ownership="none"> + <type name="FilenameCompleter" c:type="GFilenameCompleter*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="get_completion_suffix" c:identifier="g_filename_completer_get_completion_suffix"> + <doc xml:space="preserve">Obtains a completion for @initial_text from @completer.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a completed string, or %NULL if no + completion exists. This string is not owned by GIO, so remember to g_free() + it when finished.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="completer" transfer-ownership="none"> + <doc xml:space="preserve">the filename completer.</doc> + <type name="FilenameCompleter" c:type="GFilenameCompleter*"/> + </instance-parameter> + <parameter name="initial_text" transfer-ownership="none"> + <doc xml:space="preserve">text to be completed.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_completions" c:identifier="g_filename_completer_get_completions"> + <doc xml:space="preserve">Gets an array of completion strings for a given initial text.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">array of strings with possible completions for @initial_text. +This array must be freed by g_strfreev() when finished.</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="completer" transfer-ownership="none"> + <doc xml:space="preserve">the filename completer.</doc> + <type name="FilenameCompleter" c:type="GFilenameCompleter*"/> + </instance-parameter> + <parameter name="initial_text" transfer-ownership="none"> + <doc xml:space="preserve">text to be completed.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_dirs_only" c:identifier="g_filename_completer_set_dirs_only"> + <doc xml:space="preserve">If @dirs_only is %TRUE, @completer will only +complete directory names, and not file names.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="completer" transfer-ownership="none"> + <doc xml:space="preserve">the filename completer.</doc> + <type name="FilenameCompleter" c:type="GFilenameCompleter*"/> + </instance-parameter> + <parameter name="dirs_only" transfer-ownership="none"> + <doc xml:space="preserve">a #gboolean.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <glib:signal name="got-completion-data" when="last"> + <doc xml:space="preserve">Emitted when the file name completion information comes available.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + </class> + <record name="FilenameCompleterClass" c:type="GFilenameCompleterClass" glib:is-gtype-struct-for="FilenameCompleter"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="got_completion_data"> + <callback name="got_completion_data"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="filename_completer" transfer-ownership="none"> + <type name="FilenameCompleter" c:type="GFilenameCompleter*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <enumeration name="FilesystemPreviewType" glib:type-name="GFilesystemPreviewType" glib:get-type="g_filesystem_preview_type_get_type" c:type="GFilesystemPreviewType"> + <doc xml:space="preserve">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.</doc> + <member name="if_always" value="0" c:identifier="G_FILESYSTEM_PREVIEW_TYPE_IF_ALWAYS" glib:nick="if-always"> + <doc xml:space="preserve">Only preview files if user has explicitly requested it.</doc> + </member> + <member name="if_local" value="1" c:identifier="G_FILESYSTEM_PREVIEW_TYPE_IF_LOCAL" glib:nick="if-local"> + <doc xml:space="preserve">Preview files if user has requested preview of "local" files.</doc> + </member> + <member name="never" value="2" c:identifier="G_FILESYSTEM_PREVIEW_TYPE_NEVER" glib:nick="never"> + <doc xml:space="preserve">Never preview files.</doc> + </member> + </enumeration> + <class name="FilterInputStream" c:symbol-prefix="filter_input_stream" c:type="GFilterInputStream" parent="InputStream" abstract="1" glib:type-name="GFilterInputStream" glib:get-type="g_filter_input_stream_get_type" glib:type-struct="FilterInputStreamClass"> + <doc xml:space="preserve">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.</doc> + <method name="get_base_stream" c:identifier="g_filter_input_stream_get_base_stream"> + <doc xml:space="preserve">Gets the base stream for the filter stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFilterInputStream.</doc> + <type name="FilterInputStream" c:type="GFilterInputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_close_base_stream" c:identifier="g_filter_input_stream_get_close_base_stream"> + <doc xml:space="preserve">Returns whether the base stream will be closed when @stream is +closed.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the base stream will be closed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFilterInputStream.</doc> + <type name="FilterInputStream" c:type="GFilterInputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_close_base_stream" c:identifier="g_filter_input_stream_set_close_base_stream"> + <doc xml:space="preserve">Sets whether the base stream will be closed when @stream is closed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFilterInputStream.</doc> + <type name="FilterInputStream" c:type="GFilterInputStream*"/> + </instance-parameter> + <parameter name="close_base" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to close the base stream.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <property name="base-stream" writable="1" construct-only="1" transfer-ownership="none"> + <type name="InputStream"/> + </property> + <property name="close-base-stream" writable="1" construct="1" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </property> + <field name="parent_instance"> + <type name="InputStream" c:type="GInputStream"/> + </field> + <field name="base_stream"> + <type name="InputStream" c:type="GInputStream*"/> + </field> + </class> + <record name="FilterInputStreamClass" c:type="GFilterInputStreamClass" glib:is-gtype-struct-for="FilterInputStream"> + <field name="parent_class"> + <type name="InputStreamClass" c:type="GInputStreamClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <class name="FilterOutputStream" c:symbol-prefix="filter_output_stream" c:type="GFilterOutputStream" parent="OutputStream" abstract="1" glib:type-name="GFilterOutputStream" glib:get-type="g_filter_output_stream_get_type" glib:type-struct="FilterOutputStreamClass"> + <doc xml:space="preserve">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.</doc> + <method name="get_base_stream" c:identifier="g_filter_output_stream_get_base_stream"> + <doc xml:space="preserve">Gets the base stream for the filter stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFilterOutputStream.</doc> + <type name="FilterOutputStream" c:type="GFilterOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_close_base_stream" c:identifier="g_filter_output_stream_get_close_base_stream"> + <doc xml:space="preserve">Returns whether the base stream will be closed when @stream is +closed.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the base stream will be closed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFilterOutputStream.</doc> + <type name="FilterOutputStream" c:type="GFilterOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_close_base_stream" c:identifier="g_filter_output_stream_set_close_base_stream"> + <doc xml:space="preserve">Sets whether the base stream will be closed when @stream is closed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GFilterOutputStream.</doc> + <type name="FilterOutputStream" c:type="GFilterOutputStream*"/> + </instance-parameter> + <parameter name="close_base" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to close the base stream.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <property name="base-stream" writable="1" construct-only="1" transfer-ownership="none"> + <type name="OutputStream"/> + </property> + <property name="close-base-stream" writable="1" construct-only="1" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </property> + <field name="parent_instance"> + <type name="OutputStream" c:type="GOutputStream"/> + </field> + <field name="base_stream"> + <type name="OutputStream" c:type="GOutputStream*"/> + </field> + </class> + <record name="FilterOutputStreamClass" c:type="GFilterOutputStreamClass" glib:is-gtype-struct-for="FilterOutputStream"> + <field name="parent_class"> + <type name="OutputStreamClass" c:type="GOutputStreamClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <function-macro name="ICON" c:identifier="G_ICON" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ICON_GET_IFACE" c:identifier="G_ICON_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="INET_ADDRESS" c:identifier="G_INET_ADDRESS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="INET_ADDRESS_CLASS" c:identifier="G_INET_ADDRESS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="INET_ADDRESS_GET_CLASS" c:identifier="G_INET_ADDRESS_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="INET_ADDRESS_MASK" c:identifier="G_INET_ADDRESS_MASK" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="INET_ADDRESS_MASK_CLASS" c:identifier="G_INET_ADDRESS_MASK_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="INET_ADDRESS_MASK_GET_CLASS" c:identifier="G_INET_ADDRESS_MASK_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="INET_SOCKET_ADDRESS" c:identifier="G_INET_SOCKET_ADDRESS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="INET_SOCKET_ADDRESS_CLASS" c:identifier="G_INET_SOCKET_ADDRESS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="INET_SOCKET_ADDRESS_GET_CLASS" c:identifier="G_INET_SOCKET_ADDRESS_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="INITABLE" c:identifier="G_INITABLE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="INITABLE_GET_IFACE" c:identifier="G_INITABLE_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="INPUT_STREAM" c:identifier="G_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="INPUT_STREAM_CLASS" c:identifier="G_INPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="INPUT_STREAM_GET_CLASS" c:identifier="G_INPUT_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <enumeration name="IOErrorEnum" glib:type-name="GIOErrorEnum" glib:get-type="g_io_error_enum_get_type" c:type="GIOErrorEnum" glib:error-domain="g-io-error-quark"> + <doc xml:space="preserve">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.</doc> + <member name="failed" value="0" c:identifier="G_IO_ERROR_FAILED" glib:nick="failed"> + <doc xml:space="preserve">Generic error condition for when an operation fails + and no more specific #GIOErrorEnum value is defined.</doc> + </member> + <member name="not_found" value="1" c:identifier="G_IO_ERROR_NOT_FOUND" glib:nick="not-found"> + <doc xml:space="preserve">File not found.</doc> + </member> + <member name="exists" value="2" c:identifier="G_IO_ERROR_EXISTS" glib:nick="exists"> + <doc xml:space="preserve">File already exists.</doc> + </member> + <member name="is_directory" value="3" c:identifier="G_IO_ERROR_IS_DIRECTORY" glib:nick="is-directory"> + <doc xml:space="preserve">File is a directory.</doc> + </member> + <member name="not_directory" value="4" c:identifier="G_IO_ERROR_NOT_DIRECTORY" glib:nick="not-directory"> + <doc xml:space="preserve">File is not a directory.</doc> + </member> + <member name="not_empty" value="5" c:identifier="G_IO_ERROR_NOT_EMPTY" glib:nick="not-empty"> + <doc xml:space="preserve">File is a directory that isn't empty.</doc> + </member> + <member name="not_regular_file" value="6" c:identifier="G_IO_ERROR_NOT_REGULAR_FILE" glib:nick="not-regular-file"> + <doc xml:space="preserve">File is not a regular file.</doc> + </member> + <member name="not_symbolic_link" value="7" c:identifier="G_IO_ERROR_NOT_SYMBOLIC_LINK" glib:nick="not-symbolic-link"> + <doc xml:space="preserve">File is not a symbolic link.</doc> + </member> + <member name="not_mountable_file" value="8" c:identifier="G_IO_ERROR_NOT_MOUNTABLE_FILE" glib:nick="not-mountable-file"> + <doc xml:space="preserve">File cannot be mounted.</doc> + </member> + <member name="filename_too_long" value="9" c:identifier="G_IO_ERROR_FILENAME_TOO_LONG" glib:nick="filename-too-long"> + <doc xml:space="preserve">Filename is too many characters.</doc> + </member> + <member name="invalid_filename" value="10" c:identifier="G_IO_ERROR_INVALID_FILENAME" glib:nick="invalid-filename"> + <doc xml:space="preserve">Filename is invalid or contains invalid characters.</doc> + </member> + <member name="too_many_links" value="11" c:identifier="G_IO_ERROR_TOO_MANY_LINKS" glib:nick="too-many-links"> + <doc xml:space="preserve">File contains too many symbolic links.</doc> + </member> + <member name="no_space" value="12" c:identifier="G_IO_ERROR_NO_SPACE" glib:nick="no-space"> + <doc xml:space="preserve">No space left on drive.</doc> + </member> + <member name="invalid_argument" value="13" c:identifier="G_IO_ERROR_INVALID_ARGUMENT" glib:nick="invalid-argument"> + <doc xml:space="preserve">Invalid argument.</doc> + </member> + <member name="permission_denied" value="14" c:identifier="G_IO_ERROR_PERMISSION_DENIED" glib:nick="permission-denied"> + <doc xml:space="preserve">Permission denied.</doc> + </member> + <member name="not_supported" value="15" c:identifier="G_IO_ERROR_NOT_SUPPORTED" glib:nick="not-supported"> + <doc xml:space="preserve">Operation (or one of its parameters) not supported</doc> + </member> + <member name="not_mounted" value="16" c:identifier="G_IO_ERROR_NOT_MOUNTED" glib:nick="not-mounted"> + <doc xml:space="preserve">File isn't mounted.</doc> + </member> + <member name="already_mounted" value="17" c:identifier="G_IO_ERROR_ALREADY_MOUNTED" glib:nick="already-mounted"> + <doc xml:space="preserve">File is already mounted.</doc> + </member> + <member name="closed" value="18" c:identifier="G_IO_ERROR_CLOSED" glib:nick="closed"> + <doc xml:space="preserve">File was closed.</doc> + </member> + <member name="cancelled" value="19" c:identifier="G_IO_ERROR_CANCELLED" glib:nick="cancelled"> + <doc xml:space="preserve">Operation was cancelled. See #GCancellable.</doc> + </member> + <member name="pending" value="20" c:identifier="G_IO_ERROR_PENDING" glib:nick="pending"> + <doc xml:space="preserve">Operations are still pending.</doc> + </member> + <member name="read_only" value="21" c:identifier="G_IO_ERROR_READ_ONLY" glib:nick="read-only"> + <doc xml:space="preserve">File is read only.</doc> + </member> + <member name="cant_create_backup" value="22" c:identifier="G_IO_ERROR_CANT_CREATE_BACKUP" glib:nick="cant-create-backup"> + <doc xml:space="preserve">Backup couldn't be created.</doc> + </member> + <member name="wrong_etag" value="23" c:identifier="G_IO_ERROR_WRONG_ETAG" glib:nick="wrong-etag"> + <doc xml:space="preserve">File's Entity Tag was incorrect.</doc> + </member> + <member name="timed_out" value="24" c:identifier="G_IO_ERROR_TIMED_OUT" glib:nick="timed-out"> + <doc xml:space="preserve">Operation timed out.</doc> + </member> + <member name="would_recurse" value="25" c:identifier="G_IO_ERROR_WOULD_RECURSE" glib:nick="would-recurse"> + <doc xml:space="preserve">Operation would be recursive.</doc> + </member> + <member name="busy" value="26" c:identifier="G_IO_ERROR_BUSY" glib:nick="busy"> + <doc xml:space="preserve">File is busy.</doc> + </member> + <member name="would_block" value="27" c:identifier="G_IO_ERROR_WOULD_BLOCK" glib:nick="would-block"> + <doc xml:space="preserve">Operation would block.</doc> + </member> + <member name="host_not_found" value="28" c:identifier="G_IO_ERROR_HOST_NOT_FOUND" glib:nick="host-not-found"> + <doc xml:space="preserve">Host couldn't be found (remote operations).</doc> + </member> + <member name="would_merge" value="29" c:identifier="G_IO_ERROR_WOULD_MERGE" glib:nick="would-merge"> + <doc xml:space="preserve">Operation would merge files.</doc> + </member> + <member name="failed_handled" value="30" c:identifier="G_IO_ERROR_FAILED_HANDLED" glib:nick="failed-handled"> + <doc xml:space="preserve">Operation failed and a helper program has + already interacted with the user. Do not display any error dialog.</doc> + </member> + <member name="too_many_open_files" value="31" c:identifier="G_IO_ERROR_TOO_MANY_OPEN_FILES" glib:nick="too-many-open-files"> + <doc xml:space="preserve">The current process has too many files + open and can't open any more. Duplicate descriptors do count toward + this limit. Since 2.20</doc> + </member> + <member name="not_initialized" value="32" c:identifier="G_IO_ERROR_NOT_INITIALIZED" glib:nick="not-initialized"> + <doc xml:space="preserve">The object has not been initialized. Since 2.22</doc> + </member> + <member name="address_in_use" value="33" c:identifier="G_IO_ERROR_ADDRESS_IN_USE" glib:nick="address-in-use"> + <doc xml:space="preserve">The requested address is already in use. Since 2.22</doc> + </member> + <member name="partial_input" value="34" c:identifier="G_IO_ERROR_PARTIAL_INPUT" glib:nick="partial-input"> + <doc xml:space="preserve">Need more input to finish operation. Since 2.24</doc> + </member> + <member name="invalid_data" value="35" c:identifier="G_IO_ERROR_INVALID_DATA" glib:nick="invalid-data"> + <doc xml:space="preserve">The input data was invalid. Since 2.24</doc> + </member> + <member name="dbus_error" value="36" c:identifier="G_IO_ERROR_DBUS_ERROR" glib:nick="dbus-error"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="host_unreachable" value="37" c:identifier="G_IO_ERROR_HOST_UNREACHABLE" glib:nick="host-unreachable"> + <doc xml:space="preserve">Host unreachable. Since 2.26</doc> + </member> + <member name="network_unreachable" value="38" c:identifier="G_IO_ERROR_NETWORK_UNREACHABLE" glib:nick="network-unreachable"> + <doc xml:space="preserve">Network unreachable. Since 2.26</doc> + </member> + <member name="connection_refused" value="39" c:identifier="G_IO_ERROR_CONNECTION_REFUSED" glib:nick="connection-refused"> + <doc xml:space="preserve">Connection refused. Since 2.26</doc> + </member> + <member name="proxy_failed" value="40" c:identifier="G_IO_ERROR_PROXY_FAILED" glib:nick="proxy-failed"> + <doc xml:space="preserve">Connection to proxy server failed. Since 2.26</doc> + </member> + <member name="proxy_auth_failed" value="41" c:identifier="G_IO_ERROR_PROXY_AUTH_FAILED" glib:nick="proxy-auth-failed"> + <doc xml:space="preserve">Proxy authentication failed. Since 2.26</doc> + </member> + <member name="proxy_need_auth" value="42" c:identifier="G_IO_ERROR_PROXY_NEED_AUTH" glib:nick="proxy-need-auth"> + <doc xml:space="preserve">Proxy server needs authentication. Since 2.26</doc> + </member> + <member name="proxy_not_allowed" value="43" c:identifier="G_IO_ERROR_PROXY_NOT_ALLOWED" glib:nick="proxy-not-allowed"> + <doc xml:space="preserve">Proxy connection is not allowed by ruleset. + Since 2.26</doc> + </member> + <member name="broken_pipe" value="44" c:identifier="G_IO_ERROR_BROKEN_PIPE" glib:nick="broken-pipe"> + <doc xml:space="preserve">Broken pipe. Since 2.36</doc> + </member> + <member name="connection_closed" value="44" c:identifier="G_IO_ERROR_CONNECTION_CLOSED" glib:nick="connection-closed"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="not_connected" value="45" c:identifier="G_IO_ERROR_NOT_CONNECTED" glib:nick="not-connected"> + <doc xml:space="preserve">Transport endpoint is not connected. Since 2.44</doc> + </member> + <member name="message_too_large" value="46" c:identifier="G_IO_ERROR_MESSAGE_TOO_LARGE" glib:nick="message-too-large"> + <doc xml:space="preserve">Message too large. Since 2.48.</doc> + </member> + </enumeration> + <record name="IOExtension" c:type="GIOExtension" disguised="1"> + <doc xml:space="preserve">#GIOExtension is an opaque data structure and can only be accessed +using the following functions.</doc> + <method name="get_name" c:identifier="g_io_extension_get_name"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the name of @extension.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="extension" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOExtension</doc> + <type name="IOExtension" c:type="GIOExtension*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_priority" c:identifier="g_io_extension_get_priority"> + <doc xml:space="preserve">Gets the priority with which @extension was registered.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the priority of @extension</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="extension" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOExtension</doc> + <type name="IOExtension" c:type="GIOExtension*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_type" c:identifier="g_io_extension_get_type"> + <doc xml:space="preserve">Gets the type associated with @extension.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the type of @extension</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <instance-parameter name="extension" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOExtension</doc> + <type name="IOExtension" c:type="GIOExtension*"/> + </instance-parameter> + </parameters> + </method> + <method name="ref_class" c:identifier="g_io_extension_ref_class" introspectable="0"> + <doc xml:space="preserve">Gets a reference to the class for the type that is +associated with @extension.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the #GTypeClass for the type of @extension</doc> + <type name="GObject.TypeClass" c:type="GTypeClass*"/> + </return-value> + <parameters> + <instance-parameter name="extension" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOExtension</doc> + <type name="IOExtension" c:type="GIOExtension*"/> + </instance-parameter> + </parameters> + </method> + </record> + <record name="IOExtensionPoint" c:type="GIOExtensionPoint" disguised="1"> + <doc xml:space="preserve">#GIOExtensionPoint is an opaque data structure and can only be accessed +using the following functions.</doc> + <method name="get_extension_by_name" c:identifier="g_io_extension_point_get_extension_by_name"> + <doc xml:space="preserve">Finds a #GIOExtension for an extension point by name.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GIOExtension for @extension_point that has the + given name, or %NULL if there is no extension with that name</doc> + <type name="IOExtension" c:type="GIOExtension*"/> + </return-value> + <parameters> + <instance-parameter name="extension_point" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOExtensionPoint</doc> + <type name="IOExtensionPoint" c:type="GIOExtensionPoint*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the extension to get</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_extensions" c:identifier="g_io_extension_point_get_extensions"> + <doc xml:space="preserve">Gets a list of all extensions that implement this extension point. +The list is sorted by priority, beginning with the highest priority.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GList of + #GIOExtensions. The list is owned by GIO and should not be + modified.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="IOExtension"/> + </type> + </return-value> + <parameters> + <instance-parameter name="extension_point" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOExtensionPoint</doc> + <type name="IOExtensionPoint" c:type="GIOExtensionPoint*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_required_type" c:identifier="g_io_extension_point_get_required_type"> + <doc xml:space="preserve">Gets the required type for @extension_point.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GType that all implementations must have, + or #G_TYPE_INVALID if the extension point has no required type</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <instance-parameter name="extension_point" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOExtensionPoint</doc> + <type name="IOExtensionPoint" c:type="GIOExtensionPoint*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_required_type" c:identifier="g_io_extension_point_set_required_type"> + <doc xml:space="preserve">Sets the required type for @extension_point to @type. +All implementations must henceforth have this type.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="extension_point" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOExtensionPoint</doc> + <type name="IOExtensionPoint" c:type="GIOExtensionPoint*"/> + </instance-parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">the #GType to require</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </method> + <function name="implement" c:identifier="g_io_extension_point_implement"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GIOExtension object for #GType</doc> + <type name="IOExtension" c:type="GIOExtension*"/> + </return-value> + <parameters> + <parameter name="extension_point_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the extension point</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">the #GType to register as extension</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="extension_name" transfer-ownership="none"> + <doc xml:space="preserve">the name for the extension</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="priority" transfer-ownership="none"> + <doc xml:space="preserve">the priority for the extension</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="lookup" c:identifier="g_io_extension_point_lookup"> + <doc xml:space="preserve">Looks up an existing extension point.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GIOExtensionPoint, or %NULL if there + is no registered extension point with the given name.</doc> + <type name="IOExtensionPoint" c:type="GIOExtensionPoint*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the extension point</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="register" c:identifier="g_io_extension_point_register"> + <doc xml:space="preserve">Registers an extension point.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the new #GIOExtensionPoint. This object is + owned by GIO and should not be freed.</doc> + <type name="IOExtensionPoint" c:type="GIOExtensionPoint*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">The name of the extension point</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + </record> + <class name="IOModule" c:symbol-prefix="io_module" c:type="GIOModule" parent="GObject.TypeModule" glib:type-name="GIOModule" glib:get-type="g_io_module_get_type" glib:type-struct="IOModuleClass"> + <doc xml:space="preserve">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.</doc> + <implements name="GObject.TypePlugin"/> + <constructor name="new" c:identifier="g_io_module_new"> + <doc xml:space="preserve">Creates a new GIOModule that will load the specific +shared library when in use.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIOModule from given @filename, +or %NULL on error.</doc> + <type name="IOModule" c:type="GIOModule*"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">filename of the shared library module.</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <function name="query" c:identifier="g_io_module_query" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A %NULL-terminated array of strings, + listing the supported extension points of the module. The array + must be suitable for freeing with g_strfreev().</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </return-value> + </function> + <method name="load" c:identifier="g_io_module_load"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="module" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOModule.</doc> + <type name="IOModule" c:type="GIOModule*"/> + </instance-parameter> + </parameters> + </method> + <method name="unload" c:identifier="g_io_module_unload"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="module" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOModule.</doc> + <type name="IOModule" c:type="GIOModule*"/> + </instance-parameter> + </parameters> + </method> + </class> + <record name="IOModuleClass" c:type="GIOModuleClass" disguised="1" glib:is-gtype-struct-for="IOModule"/> + <record name="IOModuleScope" c:type="GIOModuleScope" disguised="1" version="2.30"> + <doc xml:space="preserve">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().</doc> + <method name="block" c:identifier="g_io_module_scope_block" version="2.30"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="scope" transfer-ownership="none"> + <doc xml:space="preserve">a module loading scope</doc> + <type name="IOModuleScope" c:type="GIOModuleScope*"/> + </instance-parameter> + <parameter name="basename" transfer-ownership="none"> + <doc xml:space="preserve">the basename to block</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="free" c:identifier="g_io_module_scope_free" version="2.30"> + <doc xml:space="preserve">Free a module scope.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="scope" transfer-ownership="none"> + <doc xml:space="preserve">a module loading scope</doc> + <type name="IOModuleScope" c:type="GIOModuleScope*"/> + </instance-parameter> + </parameters> + </method> + <function name="new" c:identifier="g_io_module_scope_new" version="2.30" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new module scope</doc> + <type name="IOModuleScope" c:type="GIOModuleScope*"/> + </return-value> + <parameters> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the new scope</doc> + <type name="IOModuleScopeFlags" c:type="GIOModuleScopeFlags"/> + </parameter> + </parameters> + </function> + </record> + <enumeration name="IOModuleScopeFlags" version="2.30" glib:type-name="GIOModuleScopeFlags" glib:get-type="g_io_module_scope_flags_get_type" c:type="GIOModuleScopeFlags"> + <doc xml:space="preserve">Flags for use with g_io_module_scope_new().</doc> + <member name="none" value="0" c:identifier="G_IO_MODULE_SCOPE_NONE" glib:nick="none"> + <doc xml:space="preserve">No module scan flags</doc> + </member> + <member name="block_duplicates" value="1" c:identifier="G_IO_MODULE_SCOPE_BLOCK_DUPLICATES" glib:nick="block-duplicates"> + <doc xml:space="preserve">When using this scope to load or + scan modules, automatically block a modules which has the same base + basename as previously loaded module.</doc> + </member> + </enumeration> + <record name="IOSchedulerJob" c:type="GIOSchedulerJob" disguised="1"> + <doc xml:space="preserve">Opaque class for defining and scheduling IO jobs.</doc> + <method name="send_to_mainloop" c:identifier="g_io_scheduler_job_send_to_mainloop" deprecated="1"> + <doc xml:space="preserve">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).</doc> + <doc-deprecated xml:space="preserve">Use g_main_context_invoke().</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The return value of @func</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="job" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOSchedulerJob</doc> + <type name="IOSchedulerJob" c:type="GIOSchedulerJob*"/> + </instance-parameter> + <parameter name="func" transfer-ownership="none" scope="notified" closure="1" destroy="2"> + <doc xml:space="preserve">a #GSourceFunc callback that will be called in the original thread</doc> + <type name="GLib.SourceFunc" c:type="GSourceFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a #GDestroyNotify for @user_data, or %NULL</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="send_to_mainloop_async" c:identifier="g_io_scheduler_job_send_to_mainloop_async" deprecated="1"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_main_context_invoke().</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="job" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOSchedulerJob</doc> + <type name="IOSchedulerJob" c:type="GIOSchedulerJob*"/> + </instance-parameter> + <parameter name="func" transfer-ownership="none" scope="notified" closure="1" destroy="2"> + <doc xml:space="preserve">a #GSourceFunc callback that will be called in the original thread</doc> + <type name="GLib.SourceFunc" c:type="GSourceFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a #GDestroyNotify for @user_data, or %NULL</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + </record> + <callback name="IOSchedulerJobFunc" c:type="GIOSchedulerJobFunc"> + <doc xml:space="preserve">I/O Job function. + +Long-running jobs should periodically check the @cancellable +to see if they have been cancelled.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if this function should be called again to + complete the job, %FALSE if the job is complete (or cancelled)</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="job" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOSchedulerJob.</doc> + <type name="IOSchedulerJob" c:type="GIOSchedulerJob*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <class name="IOStream" c:symbol-prefix="io_stream" c:type="GIOStream" version="2.22" parent="GObject.Object" abstract="1" glib:type-name="GIOStream" glib:get-type="g_io_stream_get_type" glib:type-struct="IOStreamClass"> + <doc xml:space="preserve">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).</doc> + <function name="splice_finish" c:identifier="g_io_stream_splice_finish" version="2.28" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous io stream splice operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </function> + <virtual-method name="close_async" invoker="close_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="close_finish" invoker="close_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Closes a stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if stream was successfully closed, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="close_fn" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="IOStream" c:type="GIOStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_input_stream" invoker="get_input_stream" version="2.22"> + <doc xml:space="preserve">Gets the input stream for this object. This is used +for reading.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream, owned by the #GIOStream. +Do not free.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_output_stream" invoker="get_output_stream" version="2.22"> + <doc xml:space="preserve">Gets the output stream for this object. This is used for +writing.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream, owned by the #GIOStream. +Do not free.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="clear_pending" c:identifier="g_io_stream_clear_pending" version="2.22"> + <doc xml:space="preserve">Clears the pending flag on @stream.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="close" c:identifier="g_io_stream_close" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="close_async" c:identifier="g_io_stream_close_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="close_finish" c:identifier="g_io_stream_close_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Closes a stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if stream was successfully closed, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="get_input_stream" c:identifier="g_io_stream_get_input_stream" version="2.22"> + <doc xml:space="preserve">Gets the input stream for this object. This is used +for reading.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream, owned by the #GIOStream. +Do not free.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_output_stream" c:identifier="g_io_stream_get_output_stream" version="2.22"> + <doc xml:space="preserve">Gets the output stream for this object. This is used for +writing.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream, owned by the #GIOStream. +Do not free.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="has_pending" c:identifier="g_io_stream_has_pending" version="2.22"> + <doc xml:space="preserve">Checks if a stream has pending actions.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @stream has pending actions.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_closed" c:identifier="g_io_stream_is_closed" version="2.22"> + <doc xml:space="preserve">Checks if a stream is closed.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the stream is closed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_pending" c:identifier="g_io_stream_set_pending" version="2.22" throws="1"> + <doc xml:space="preserve">Sets @stream to have actions pending. If the pending flag is +already set or @stream is closed, it will return %FALSE and set +@error.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if pending was previously unset and is now set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="splice_async" c:identifier="g_io_stream_splice_async" version="2.28"> + <doc xml:space="preserve">Asynchronously 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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream1" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream.</doc> + <type name="IOStream" c:type="GIOStream*"/> + </instance-parameter> + <parameter name="stream2" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream.</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GIOStreamSpliceFlags.</doc> + <type name="IOStreamSpliceFlags" c:type="GIOStreamSpliceFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <property name="closed" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="input-stream" transfer-ownership="none"> + <type name="InputStream"/> + </property> + <property name="output-stream" transfer-ownership="none"> + <type name="OutputStream"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="IOStreamPrivate" c:type="GIOStreamPrivate*"/> + </field> + </class> + <record name="IOStreamAdapter" c:type="GIOStreamAdapter" disguised="1"/> + <record name="IOStreamClass" c:type="GIOStreamClass" glib:is-gtype-struct-for="IOStream"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="get_input_stream"> + <callback name="get_input_stream"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream, owned by the #GIOStream. +Do not free.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_output_stream"> + <callback name="get_output_stream"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream, owned by the #GIOStream. +Do not free.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="close_fn"> + <callback name="close_fn" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="close_async"> + <callback name="close_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="close_finish"> + <callback name="close_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if stream was successfully closed, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved6" introspectable="0"> + <callback name="_g_reserved6"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved7" introspectable="0"> + <callback name="_g_reserved7"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved8" introspectable="0"> + <callback name="_g_reserved8"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved9" introspectable="0"> + <callback name="_g_reserved9"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved10" introspectable="0"> + <callback name="_g_reserved10"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="IOStreamPrivate" c:type="GIOStreamPrivate" disguised="1"/> + <bitfield name="IOStreamSpliceFlags" version="2.28" glib:type-name="GIOStreamSpliceFlags" glib:get-type="g_io_stream_splice_flags_get_type" c:type="GIOStreamSpliceFlags"> + <doc xml:space="preserve">GIOStreamSpliceFlags determine how streams should be spliced.</doc> + <member name="none" value="0" c:identifier="G_IO_STREAM_SPLICE_NONE" glib:nick="none"> + <doc xml:space="preserve">Do not close either stream.</doc> + </member> + <member name="close_stream1" value="1" c:identifier="G_IO_STREAM_SPLICE_CLOSE_STREAM1" glib:nick="close-stream1"> + <doc xml:space="preserve">Close the first stream after + the splice.</doc> + </member> + <member name="close_stream2" value="2" c:identifier="G_IO_STREAM_SPLICE_CLOSE_STREAM2" glib:nick="close-stream2"> + <doc xml:space="preserve">Close the second stream after + the splice.</doc> + </member> + <member name="wait_for_both" value="4" c:identifier="G_IO_STREAM_SPLICE_WAIT_FOR_BOTH" glib:nick="wait-for-both"> + <doc xml:space="preserve">Wait for both splice operations to finish + before calling the callback.</doc> + </member> + </bitfield> + <function-macro name="IO_IS_MODULE" c:identifier="G_IO_IS_MODULE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IO_IS_MODULE_CLASS" c:identifier="G_IO_IS_MODULE_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IO_MODULE" c:identifier="G_IO_MODULE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IO_MODULE_CLASS" c:identifier="G_IO_MODULE_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IO_MODULE_GET_CLASS" c:identifier="G_IO_MODULE_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IO_STREAM" c:identifier="G_IO_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IO_STREAM_CLASS" c:identifier="G_IO_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IO_STREAM_GET_CLASS" c:identifier="G_IO_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_ACTION" c:identifier="G_IS_ACTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_ACTION_GROUP" c:identifier="G_IS_ACTION_GROUP" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_ACTION_MAP" c:identifier="G_IS_ACTION_MAP" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_APPLICATION" c:identifier="G_IS_APPLICATION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_APPLICATION_CLASS" c:identifier="G_IS_APPLICATION_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_APPLICATION_COMMAND_LINE" c:identifier="G_IS_APPLICATION_COMMAND_LINE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_APPLICATION_COMMAND_LINE_CLASS" c:identifier="G_IS_APPLICATION_COMMAND_LINE_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_APP_INFO" c:identifier="G_IS_APP_INFO" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_APP_INFO_MONITOR" c:identifier="G_IS_APP_INFO_MONITOR" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_APP_LAUNCH_CONTEXT" c:identifier="G_IS_APP_LAUNCH_CONTEXT" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_APP_LAUNCH_CONTEXT_CLASS" c:identifier="G_IS_APP_LAUNCH_CONTEXT_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_ASYNC_INITABLE" c:identifier="G_IS_ASYNC_INITABLE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_ASYNC_RESULT" c:identifier="G_IS_ASYNC_RESULT" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_BUFFERED_INPUT_STREAM" c:identifier="G_IS_BUFFERED_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_BUFFERED_INPUT_STREAM_CLASS" c:identifier="G_IS_BUFFERED_INPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_BUFFERED_OUTPUT_STREAM" c:identifier="G_IS_BUFFERED_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_BUFFERED_OUTPUT_STREAM_CLASS" c:identifier="G_IS_BUFFERED_OUTPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_BYTES_ICON" c:identifier="G_IS_BYTES_ICON" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_CANCELLABLE" c:identifier="G_IS_CANCELLABLE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_CANCELLABLE_CLASS" c:identifier="G_IS_CANCELLABLE_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_CHARSET_CONVERTER" c:identifier="G_IS_CHARSET_CONVERTER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_CHARSET_CONVERTER_CLASS" c:identifier="G_IS_CHARSET_CONVERTER_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_CONVERTER" c:identifier="G_IS_CONVERTER" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_CONVERTER_INPUT_STREAM" c:identifier="G_IS_CONVERTER_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_CONVERTER_INPUT_STREAM_CLASS" c:identifier="G_IS_CONVERTER_INPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_CONVERTER_OUTPUT_STREAM" c:identifier="G_IS_CONVERTER_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_CONVERTER_OUTPUT_STREAM_CLASS" c:identifier="G_IS_CONVERTER_OUTPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_CREDENTIALS" c:identifier="G_IS_CREDENTIALS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_CREDENTIALS_CLASS" c:identifier="G_IS_CREDENTIALS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DATAGRAM_BASED" c:identifier="G_IS_DATAGRAM_BASED" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DATA_INPUT_STREAM" c:identifier="G_IS_DATA_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DATA_INPUT_STREAM_CLASS" c:identifier="G_IS_DATA_INPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DATA_OUTPUT_STREAM" c:identifier="G_IS_DATA_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DATA_OUTPUT_STREAM_CLASS" c:identifier="G_IS_DATA_OUTPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_ACTION_GROUP" c:identifier="G_IS_DBUS_ACTION_GROUP" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_ACTION_GROUP_CLASS" c:identifier="G_IS_DBUS_ACTION_GROUP_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_AUTH_OBSERVER" c:identifier="G_IS_DBUS_AUTH_OBSERVER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_CONNECTION" c:identifier="G_IS_DBUS_CONNECTION" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_INTERFACE" c:identifier="G_IS_DBUS_INTERFACE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_INTERFACE_SKELETON" c:identifier="G_IS_DBUS_INTERFACE_SKELETON" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_INTERFACE_SKELETON_CLASS" c:identifier="G_IS_DBUS_INTERFACE_SKELETON_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_MENU_MODEL" c:identifier="G_IS_DBUS_MENU_MODEL" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_MESSAGE" c:identifier="G_IS_DBUS_MESSAGE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_METHOD_INVOCATION" c:identifier="G_IS_DBUS_METHOD_INVOCATION" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_OBJECT" c:identifier="G_IS_DBUS_OBJECT" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_OBJECT_MANAGER" c:identifier="G_IS_DBUS_OBJECT_MANAGER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_OBJECT_MANAGER_CLIENT" c:identifier="G_IS_DBUS_OBJECT_MANAGER_CLIENT" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_OBJECT_MANAGER_CLIENT_CLASS" c:identifier="G_IS_DBUS_OBJECT_MANAGER_CLIENT_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_OBJECT_MANAGER_SERVER" c:identifier="G_IS_DBUS_OBJECT_MANAGER_SERVER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_OBJECT_MANAGER_SERVER_CLASS" c:identifier="G_IS_DBUS_OBJECT_MANAGER_SERVER_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_OBJECT_PROXY" c:identifier="G_IS_DBUS_OBJECT_PROXY" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_OBJECT_PROXY_CLASS" c:identifier="G_IS_DBUS_OBJECT_PROXY_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_OBJECT_SKELETON" c:identifier="G_IS_DBUS_OBJECT_SKELETON" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_OBJECT_SKELETON_CLASS" c:identifier="G_IS_DBUS_OBJECT_SKELETON_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_PROXY" c:identifier="G_IS_DBUS_PROXY" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_PROXY_CLASS" c:identifier="G_IS_DBUS_PROXY_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DBUS_SERVER" c:identifier="G_IS_DBUS_SERVER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DESKTOP_APP_INFO" c:identifier="G_IS_DESKTOP_APP_INFO" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DESKTOP_APP_INFO_CLASS" c:identifier="G_IS_DESKTOP_APP_INFO_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DESKTOP_APP_INFO_LOOKUP" c:identifier="G_IS_DESKTOP_APP_INFO_LOOKUP" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DRIVE" c:identifier="G_IS_DRIVE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DTLS_CLIENT_CONNECTION" c:identifier="G_IS_DTLS_CLIENT_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DTLS_CONNECTION" c:identifier="G_IS_DTLS_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DTLS_SERVER_CONNECTION" c:identifier="G_IS_DTLS_SERVER_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_EMBLEM" c:identifier="G_IS_EMBLEM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_EMBLEMED_ICON" c:identifier="G_IS_EMBLEMED_ICON" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_EMBLEMED_ICON_CLASS" c:identifier="G_IS_EMBLEMED_ICON_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_EMBLEM_CLASS" c:identifier="G_IS_EMBLEM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILE" c:identifier="G_IS_FILE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILENAME_COMPLETER" c:identifier="G_IS_FILENAME_COMPLETER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILENAME_COMPLETER_CLASS" c:identifier="G_IS_FILENAME_COMPLETER_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILE_DESCRIPTOR_BASED" c:identifier="G_IS_FILE_DESCRIPTOR_BASED" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILE_ENUMERATOR" c:identifier="G_IS_FILE_ENUMERATOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILE_ENUMERATOR_CLASS" c:identifier="G_IS_FILE_ENUMERATOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILE_ICON" c:identifier="G_IS_FILE_ICON" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILE_ICON_CLASS" c:identifier="G_IS_FILE_ICON_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILE_INFO" c:identifier="G_IS_FILE_INFO" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILE_INFO_CLASS" c:identifier="G_IS_FILE_INFO_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILE_INPUT_STREAM" c:identifier="G_IS_FILE_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILE_INPUT_STREAM_CLASS" c:identifier="G_IS_FILE_INPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILE_IO_STREAM" c:identifier="G_IS_FILE_IO_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILE_IO_STREAM_CLASS" c:identifier="G_IS_FILE_IO_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILE_MONITOR" c:identifier="G_IS_FILE_MONITOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILE_MONITOR_CLASS" c:identifier="G_IS_FILE_MONITOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILE_OUTPUT_STREAM" c:identifier="G_IS_FILE_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILE_OUTPUT_STREAM_CLASS" c:identifier="G_IS_FILE_OUTPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILTER_INPUT_STREAM" c:identifier="G_IS_FILTER_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILTER_INPUT_STREAM_CLASS" c:identifier="G_IS_FILTER_INPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILTER_OUTPUT_STREAM" c:identifier="G_IS_FILTER_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_FILTER_OUTPUT_STREAM_CLASS" c:identifier="G_IS_FILTER_OUTPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_ICON" c:identifier="G_IS_ICON" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_INET_ADDRESS" c:identifier="G_IS_INET_ADDRESS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_INET_ADDRESS_CLASS" c:identifier="G_IS_INET_ADDRESS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_INET_ADDRESS_MASK" c:identifier="G_IS_INET_ADDRESS_MASK" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_INET_ADDRESS_MASK_CLASS" c:identifier="G_IS_INET_ADDRESS_MASK_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_INET_SOCKET_ADDRESS" c:identifier="G_IS_INET_SOCKET_ADDRESS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_INET_SOCKET_ADDRESS_CLASS" c:identifier="G_IS_INET_SOCKET_ADDRESS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_INITABLE" c:identifier="G_IS_INITABLE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_INPUT_STREAM" c:identifier="G_IS_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_INPUT_STREAM_CLASS" c:identifier="G_IS_INPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_IO_STREAM" c:identifier="G_IS_IO_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_IO_STREAM_CLASS" c:identifier="G_IS_IO_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_LOADABLE_ICON" c:identifier="G_IS_LOADABLE_ICON" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MEMORY_INPUT_STREAM" c:identifier="G_IS_MEMORY_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MEMORY_INPUT_STREAM_CLASS" c:identifier="G_IS_MEMORY_INPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MEMORY_MONITOR" c:identifier="G_IS_MEMORY_MONITOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MEMORY_OUTPUT_STREAM" c:identifier="G_IS_MEMORY_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MEMORY_OUTPUT_STREAM_CLASS" c:identifier="G_IS_MEMORY_OUTPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MENU" c:identifier="G_IS_MENU" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MENU_ATTRIBUTE_ITER" c:identifier="G_IS_MENU_ATTRIBUTE_ITER" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MENU_ATTRIBUTE_ITER_CLASS" c:identifier="G_IS_MENU_ATTRIBUTE_ITER_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MENU_ITEM" c:identifier="G_IS_MENU_ITEM" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MENU_LINK_ITER" c:identifier="G_IS_MENU_LINK_ITER" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MENU_LINK_ITER_CLASS" c:identifier="G_IS_MENU_LINK_ITER_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MENU_MODEL" c:identifier="G_IS_MENU_MODEL" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MENU_MODEL_CLASS" c:identifier="G_IS_MENU_MODEL_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MOUNT" c:identifier="G_IS_MOUNT" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MOUNT_OPERATION" c:identifier="G_IS_MOUNT_OPERATION" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MOUNT_OPERATION_CLASS" c:identifier="G_IS_MOUNT_OPERATION_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_NATIVE_SOCKET_ADDRESS" c:identifier="G_IS_NATIVE_SOCKET_ADDRESS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_NATIVE_SOCKET_ADDRESS_CLASS" c:identifier="G_IS_NATIVE_SOCKET_ADDRESS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_NATIVE_VOLUME_MONITOR" c:identifier="G_IS_NATIVE_VOLUME_MONITOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_NATIVE_VOLUME_MONITOR_CLASS" c:identifier="G_IS_NATIVE_VOLUME_MONITOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_NETWORK_ADDRESS" c:identifier="G_IS_NETWORK_ADDRESS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_NETWORK_ADDRESS_CLASS" c:identifier="G_IS_NETWORK_ADDRESS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_NETWORK_MONITOR" c:identifier="G_IS_NETWORK_MONITOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_NETWORK_SERVICE" c:identifier="G_IS_NETWORK_SERVICE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_NETWORK_SERVICE_CLASS" c:identifier="G_IS_NETWORK_SERVICE_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_NOTIFICATION" c:identifier="G_IS_NOTIFICATION" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_OUTPUT_STREAM" c:identifier="G_IS_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_OUTPUT_STREAM_CLASS" c:identifier="G_IS_OUTPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PERMISSION" c:identifier="G_IS_PERMISSION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PERMISSION_CLASS" c:identifier="G_IS_PERMISSION_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_POLLABLE_INPUT_STREAM" c:identifier="G_IS_POLLABLE_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_POLLABLE_OUTPUT_STREAM" c:identifier="G_IS_POLLABLE_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PROPERTY_ACTION" c:identifier="G_IS_PROPERTY_ACTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PROXY" c:identifier="G_IS_PROXY" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PROXY_ADDRESS" c:identifier="G_IS_PROXY_ADDRESS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PROXY_ADDRESS_CLASS" c:identifier="G_IS_PROXY_ADDRESS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PROXY_ADDRESS_ENUMERATOR" c:identifier="G_IS_PROXY_ADDRESS_ENUMERATOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PROXY_ADDRESS_ENUMERATOR_CLASS" c:identifier="G_IS_PROXY_ADDRESS_ENUMERATOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_PROXY_RESOLVER" c:identifier="G_IS_PROXY_RESOLVER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_REMOTE_ACTION_GROUP" c:identifier="G_IS_REMOTE_ACTION_GROUP" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_RESOLVER" c:identifier="G_IS_RESOLVER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_RESOLVER_CLASS" c:identifier="G_IS_RESOLVER_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SEEKABLE" c:identifier="G_IS_SEEKABLE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SETTINGS" c:identifier="G_IS_SETTINGS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SETTINGS_BACKEND" c:identifier="G_IS_SETTINGS_BACKEND" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SETTINGS_BACKEND_CLASS" c:identifier="G_IS_SETTINGS_BACKEND_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SETTINGS_CLASS" c:identifier="G_IS_SETTINGS_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SIMPLE_ACTION" c:identifier="G_IS_SIMPLE_ACTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SIMPLE_ACTION_GROUP" c:identifier="G_IS_SIMPLE_ACTION_GROUP" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SIMPLE_ACTION_GROUP_CLASS" c:identifier="G_IS_SIMPLE_ACTION_GROUP_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SIMPLE_ASYNC_RESULT" c:identifier="G_IS_SIMPLE_ASYNC_RESULT" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SIMPLE_ASYNC_RESULT_CLASS" c:identifier="G_IS_SIMPLE_ASYNC_RESULT_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SIMPLE_IO_STREAM" c:identifier="G_IS_SIMPLE_IO_STREAM" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SIMPLE_PERMISSION" c:identifier="G_IS_SIMPLE_PERMISSION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SIMPLE_PROXY_RESOLVER" c:identifier="G_IS_SIMPLE_PROXY_RESOLVER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SIMPLE_PROXY_RESOLVER_CLASS" c:identifier="G_IS_SIMPLE_PROXY_RESOLVER_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET" c:identifier="G_IS_SOCKET" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET_ADDRESS" c:identifier="G_IS_SOCKET_ADDRESS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET_ADDRESS_CLASS" c:identifier="G_IS_SOCKET_ADDRESS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET_ADDRESS_ENUMERATOR" c:identifier="G_IS_SOCKET_ADDRESS_ENUMERATOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET_ADDRESS_ENUMERATOR_CLASS" c:identifier="G_IS_SOCKET_ADDRESS_ENUMERATOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET_CLASS" c:identifier="G_IS_SOCKET_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET_CLIENT" c:identifier="G_IS_SOCKET_CLIENT" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET_CLIENT_CLASS" c:identifier="G_IS_SOCKET_CLIENT_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET_CONNECTABLE" c:identifier="G_IS_SOCKET_CONNECTABLE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET_CONNECTION" c:identifier="G_IS_SOCKET_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET_CONNECTION_CLASS" c:identifier="G_IS_SOCKET_CONNECTION_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET_CONTROL_MESSAGE" c:identifier="G_IS_SOCKET_CONTROL_MESSAGE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET_CONTROL_MESSAGE_CLASS" c:identifier="G_IS_SOCKET_CONTROL_MESSAGE_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET_LISTENER" c:identifier="G_IS_SOCKET_LISTENER" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET_LISTENER_CLASS" c:identifier="G_IS_SOCKET_LISTENER_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET_SERVICE" c:identifier="G_IS_SOCKET_SERVICE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SOCKET_SERVICE_CLASS" c:identifier="G_IS_SOCKET_SERVICE_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SUBPROCESS" c:identifier="G_IS_SUBPROCESS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SUBPROCESS_LAUNCHER" c:identifier="G_IS_SUBPROCESS_LAUNCHER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TASK" c:identifier="G_IS_TASK" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TASK_CLASS" c:identifier="G_IS_TASK_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TCP_CONNECTION" c:identifier="G_IS_TCP_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TCP_CONNECTION_CLASS" c:identifier="G_IS_TCP_CONNECTION_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TCP_WRAPPER_CONNECTION" c:identifier="G_IS_TCP_WRAPPER_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TCP_WRAPPER_CONNECTION_CLASS" c:identifier="G_IS_TCP_WRAPPER_CONNECTION_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TEST_DBUS" c:identifier="G_IS_TEST_DBUS" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_THEMED_ICON" c:identifier="G_IS_THEMED_ICON" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_THEMED_ICON_CLASS" c:identifier="G_IS_THEMED_ICON_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_THREADED_SOCKET_SERVICE" c:identifier="G_IS_THREADED_SOCKET_SERVICE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_THREADED_SOCKET_SERVICE_CLASS" c:identifier="G_IS_THREADED_SOCKET_SERVICE_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TLS_BACKEND" c:identifier="G_IS_TLS_BACKEND" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TLS_CERTIFICATE" c:identifier="G_IS_TLS_CERTIFICATE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TLS_CERTIFICATE_CLASS" c:identifier="G_IS_TLS_CERTIFICATE_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TLS_CLIENT_CONNECTION" c:identifier="G_IS_TLS_CLIENT_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TLS_CONNECTION" c:identifier="G_IS_TLS_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TLS_CONNECTION_CLASS" c:identifier="G_IS_TLS_CONNECTION_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TLS_DATABASE" c:identifier="G_IS_TLS_DATABASE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TLS_DATABASE_CLASS" c:identifier="G_IS_TLS_DATABASE_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TLS_FILE_DATABASE" c:identifier="G_IS_TLS_FILE_DATABASE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TLS_INTERACTION" c:identifier="G_IS_TLS_INTERACTION" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TLS_INTERACTION_CLASS" c:identifier="G_IS_TLS_INTERACTION_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TLS_PASSWORD" c:identifier="G_IS_TLS_PASSWORD" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TLS_PASSWORD_CLASS" c:identifier="G_IS_TLS_PASSWORD_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_TLS_SERVER_CONNECTION" c:identifier="G_IS_TLS_SERVER_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_UNIX_CONNECTION" c:identifier="G_IS_UNIX_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_UNIX_CONNECTION_CLASS" c:identifier="G_IS_UNIX_CONNECTION_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_UNIX_CREDENTIALS_MESSAGE" c:identifier="G_IS_UNIX_CREDENTIALS_MESSAGE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_UNIX_CREDENTIALS_MESSAGE_CLASS" c:identifier="G_IS_UNIX_CREDENTIALS_MESSAGE_CLASS" introspectable="0"> + <parameters> + <parameter name="c"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_UNIX_FD_LIST" c:identifier="G_IS_UNIX_FD_LIST" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_UNIX_FD_LIST_CLASS" c:identifier="G_IS_UNIX_FD_LIST_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_UNIX_FD_MESSAGE" c:identifier="G_IS_UNIX_FD_MESSAGE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_UNIX_FD_MESSAGE_CLASS" c:identifier="G_IS_UNIX_FD_MESSAGE_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_UNIX_INPUT_STREAM" c:identifier="G_IS_UNIX_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_UNIX_INPUT_STREAM_CLASS" c:identifier="G_IS_UNIX_INPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_UNIX_MOUNT_MONITOR" c:identifier="G_IS_UNIX_MOUNT_MONITOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_UNIX_MOUNT_MONITOR_CLASS" c:identifier="G_IS_UNIX_MOUNT_MONITOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_UNIX_OUTPUT_STREAM" c:identifier="G_IS_UNIX_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_UNIX_OUTPUT_STREAM_CLASS" c:identifier="G_IS_UNIX_OUTPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_UNIX_SOCKET_ADDRESS" c:identifier="G_IS_UNIX_SOCKET_ADDRESS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_UNIX_SOCKET_ADDRESS_CLASS" c:identifier="G_IS_UNIX_SOCKET_ADDRESS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_VFS" c:identifier="G_IS_VFS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_VFS_CLASS" c:identifier="G_IS_VFS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_VOLUME" c:identifier="G_IS_VOLUME" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_VOLUME_MONITOR" c:identifier="G_IS_VOLUME_MONITOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_VOLUME_MONITOR_CLASS" c:identifier="G_IS_VOLUME_MONITOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_ZLIB_COMPRESSOR" c:identifier="G_IS_ZLIB_COMPRESSOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_ZLIB_COMPRESSOR_CLASS" c:identifier="G_IS_ZLIB_COMPRESSOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_ZLIB_DECOMPRESSOR" c:identifier="G_IS_ZLIB_DECOMPRESSOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_ZLIB_DECOMPRESSOR_CLASS" c:identifier="G_IS_ZLIB_DECOMPRESSOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <interface name="Icon" c:symbol-prefix="icon" c:type="GIcon" glib:type-name="GIcon" glib:get-type="g_icon_get_type" glib:type-struct="IconIface"> + <doc xml:space="preserve">#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.</doc> + <function name="deserialize" c:identifier="g_icon_deserialize" version="2.38"> + <doc xml:space="preserve">Deserializes a #GIcon previously serialized using g_icon_serialize().</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GIcon, or %NULL when deserialization fails.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant created with g_icon_serialize()</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <function name="hash" c:identifier="g_icon_hash"> + <doc xml:space="preserve">Gets a hash for an icon.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #guint containing a hash for the @icon, suitable for +use in a #GHashTable or similar data structure.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">#gconstpointer to an icon object.</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="new_for_string" c:identifier="g_icon_new_for_string" version="2.20" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">An object implementing the #GIcon + interface or %NULL if @error is set.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">A string obtained via g_icon_to_string().</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <virtual-method name="equal" invoker="equal"> + <doc xml:space="preserve">Checks if two icons are equal.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @icon1 is equal to @icon2. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="icon1" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">pointer to the first #GIcon.</doc> + <type name="Icon" c:type="GIcon*"/> + </instance-parameter> + <parameter name="icon2" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">pointer to the second #GIcon.</doc> + <type name="Icon" c:type="GIcon*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="hash" invoker="hash"> + <doc xml:space="preserve">Gets a hash for an icon.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #guint containing a hash for the @icon, suitable for +use in a #GHashTable or similar data structure.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">#gconstpointer to an icon object.</doc> + <type name="Icon" c:type="GIcon*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="serialize" invoker="serialize" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GIcon</doc> + <type name="Icon" c:type="GIcon*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="to_tokens" invoker="to_string" version="2.20" introspectable="0"> + <doc xml:space="preserve">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`).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">An allocated NUL-terminated UTF8 string or +%NULL if @icon can't be serialized. Use g_free() to free.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GIcon.</doc> + <type name="Icon" c:type="GIcon*"/> + </instance-parameter> + <parameter name="tokens" transfer-ownership="none"> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="out_version" transfer-ownership="none"> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </virtual-method> + <method name="equal" c:identifier="g_icon_equal"> + <doc xml:space="preserve">Checks if two icons are equal.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @icon1 is equal to @icon2. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="icon1" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">pointer to the first #GIcon.</doc> + <type name="Icon" c:type="GIcon*"/> + </instance-parameter> + <parameter name="icon2" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">pointer to the second #GIcon.</doc> + <type name="Icon" c:type="GIcon*"/> + </parameter> + </parameters> + </method> + <method name="serialize" c:identifier="g_icon_serialize" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GIcon</doc> + <type name="Icon" c:type="GIcon*"/> + </instance-parameter> + </parameters> + </method> + <method name="to_string" c:identifier="g_icon_to_string" version="2.20"> + <doc xml:space="preserve">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`).</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">An allocated NUL-terminated UTF8 string or +%NULL if @icon can't be serialized. Use g_free() to free.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GIcon.</doc> + <type name="Icon" c:type="GIcon*"/> + </instance-parameter> + </parameters> + </method> + </interface> + <record name="IconIface" c:type="GIconIface" glib:is-gtype-struct-for="Icon"> + <doc xml:space="preserve">GIconIface is used to implement GIcon types for various +different systems. See #GThemedIcon and #GLoadableIcon for +examples of how to implement this interface.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="hash"> + <callback name="hash"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #guint containing a hash for the @icon, suitable for +use in a #GHashTable or similar data structure.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">#gconstpointer to an icon object.</doc> + <type name="Icon" c:type="GIcon*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="equal"> + <callback name="equal"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @icon1 is equal to @icon2. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="icon1" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">pointer to the first #GIcon.</doc> + <type name="Icon" c:type="GIcon*"/> + </parameter> + <parameter name="icon2" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">pointer to the second #GIcon.</doc> + <type name="Icon" c:type="GIcon*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="to_tokens" introspectable="0"> + <callback name="to_tokens" introspectable="0"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">An allocated NUL-terminated UTF8 string or +%NULL if @icon can't be serialized. Use g_free() to free.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GIcon.</doc> + <type name="Icon" c:type="GIcon*"/> + </parameter> + <parameter name="tokens" transfer-ownership="none"> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="out_version" transfer-ownership="none"> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="from_tokens" introspectable="0"> + <callback name="from_tokens" introspectable="0" throws="1"> + <return-value> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="tokens" transfer-ownership="none"> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="num_tokens" transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="version" transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </callback> + </field> + <field name="serialize"> + <callback name="serialize"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GIcon</doc> + <type name="Icon" c:type="GIcon*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="InetAddress" c:symbol-prefix="inet_address" c:type="GInetAddress" parent="GObject.Object" glib:type-name="GInetAddress" glib:get-type="g_inet_address_get_type" glib:type-struct="InetAddressClass"> + <doc xml:space="preserve">#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).</doc> + <constructor name="new_any" c:identifier="g_inet_address_new_any" version="2.22"> + <doc xml:space="preserve">Creates a #GInetAddress for the "any" address (unassigned/"don't +care") for @family.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GInetAddress corresponding to the "any" address +for @family. + Free the returned object with g_object_unref().</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </return-value> + <parameters> + <parameter name="family" transfer-ownership="none"> + <doc xml:space="preserve">the address family</doc> + <type name="SocketFamily" c:type="GSocketFamily"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_bytes" c:identifier="g_inet_address_new_from_bytes" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GInetAddress corresponding to @family and @bytes. + Free the returned object with g_object_unref().</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </return-value> + <parameters> + <parameter name="bytes" transfer-ownership="none"> + <doc xml:space="preserve">raw address data</doc> + <array zero-terminated="0" c:type="const guint8*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="family" transfer-ownership="none"> + <doc xml:space="preserve">the address family of @bytes</doc> + <type name="SocketFamily" c:type="GSocketFamily"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_string" c:identifier="g_inet_address_new_from_string" version="2.22"> + <doc xml:space="preserve">Parses @string as an IP address and creates a new #GInetAddress.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new #GInetAddress corresponding +to @string, or %NULL if @string could not be parsed. + Free the returned object with g_object_unref().</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">a string representation of an IP address</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_loopback" c:identifier="g_inet_address_new_loopback" version="2.22"> + <doc xml:space="preserve">Creates a #GInetAddress for the loopback address for @family.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GInetAddress corresponding to the loopback address +for @family. + Free the returned object with g_object_unref().</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </return-value> + <parameters> + <parameter name="family" transfer-ownership="none"> + <doc xml:space="preserve">the address family</doc> + <type name="SocketFamily" c:type="GSocketFamily"/> + </parameter> + </parameters> + </constructor> + <virtual-method name="to_bytes" invoker="to_bytes" version="2.22" introspectable="0"> + <doc xml:space="preserve">Gets the raw binary address data from @address.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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().</doc> + <type name="guint8" c:type="const guint8*"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="to_string" invoker="to_string" version="2.22"> + <doc xml:space="preserve">Converts @address to string form.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a representation of @address as a string, which should be +freed after use.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="equal" c:identifier="g_inet_address_equal" version="2.30"> + <doc xml:space="preserve">Checks if two #GInetAddress instances are equal, e.g. the same address.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @address and @other_address are equal, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">A #GInetAddress.</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + <parameter name="other_address" transfer-ownership="none"> + <doc xml:space="preserve">Another #GInetAddress.</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + </parameters> + </method> + <method name="get_family" c:identifier="g_inet_address_get_family" version="2.22"> + <doc xml:space="preserve">Gets @address's family</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@address's family</doc> + <type name="SocketFamily" c:type="GSocketFamily"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_any" c:identifier="g_inet_address_get_is_any" version="2.22"> + <doc xml:space="preserve">Tests whether @address is the "any" address for its family.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @address is the "any" address for its family.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_link_local" c:identifier="g_inet_address_get_is_link_local" version="2.22"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @address is a link-local address.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_loopback" c:identifier="g_inet_address_get_is_loopback" version="2.22"> + <doc xml:space="preserve">Tests whether @address is the loopback address for its family.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @address is the loopback address for its family.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_mc_global" c:identifier="g_inet_address_get_is_mc_global" version="2.22"> + <doc xml:space="preserve">Tests whether @address is a global multicast address.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @address is a global multicast address.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_mc_link_local" c:identifier="g_inet_address_get_is_mc_link_local" version="2.22"> + <doc xml:space="preserve">Tests whether @address is a link-local multicast address.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @address is a link-local multicast address.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_mc_node_local" c:identifier="g_inet_address_get_is_mc_node_local" version="2.22"> + <doc xml:space="preserve">Tests whether @address is a node-local multicast address.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @address is a node-local multicast address.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_mc_org_local" c:identifier="g_inet_address_get_is_mc_org_local" version="2.22"> + <doc xml:space="preserve">Tests whether @address is an organization-local multicast address.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @address is an organization-local multicast address.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_mc_site_local" c:identifier="g_inet_address_get_is_mc_site_local" version="2.22"> + <doc xml:space="preserve">Tests whether @address is a site-local multicast address.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @address is a site-local multicast address.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_multicast" c:identifier="g_inet_address_get_is_multicast" version="2.22"> + <doc xml:space="preserve">Tests whether @address is a multicast address.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @address is a multicast address.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_site_local" c:identifier="g_inet_address_get_is_site_local" version="2.22"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @address is a site-local address.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_native_size" c:identifier="g_inet_address_get_native_size" version="2.22"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes used for the native version of @address.</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="to_bytes" c:identifier="g_inet_address_to_bytes" version="2.22" introspectable="0"> + <doc xml:space="preserve">Gets the raw binary address data from @address.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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().</doc> + <type name="guint8" c:type="const guint8*"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="to_string" c:identifier="g_inet_address_to_string" version="2.22"> + <doc xml:space="preserve">Converts @address to string form.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a representation of @address as a string, which should be +freed after use.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </instance-parameter> + </parameters> + </method> + <property name="bytes" writable="1" construct-only="1" transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </property> + <property name="family" writable="1" construct-only="1" transfer-ownership="none"> + <type name="SocketFamily"/> + </property> + <property name="is-any" version="2.22" transfer-ownership="none"> + <doc xml:space="preserve">Whether this is the "any" address for its family. +See g_inet_address_get_is_any().</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="is-link-local" version="2.22" transfer-ownership="none"> + <doc xml:space="preserve">Whether this is a link-local address. +See g_inet_address_get_is_link_local().</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="is-loopback" version="2.22" transfer-ownership="none"> + <doc xml:space="preserve">Whether this is the loopback address for its family. +See g_inet_address_get_is_loopback().</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="is-mc-global" version="2.22" transfer-ownership="none"> + <doc xml:space="preserve">Whether this is a global multicast address. +See g_inet_address_get_is_mc_global().</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="is-mc-link-local" version="2.22" transfer-ownership="none"> + <doc xml:space="preserve">Whether this is a link-local multicast address. +See g_inet_address_get_is_mc_link_local().</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="is-mc-node-local" version="2.22" transfer-ownership="none"> + <doc xml:space="preserve">Whether this is a node-local multicast address. +See g_inet_address_get_is_mc_node_local().</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="is-mc-org-local" version="2.22" transfer-ownership="none"> + <doc xml:space="preserve">Whether this is an organization-local multicast address. +See g_inet_address_get_is_mc_org_local().</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="is-mc-site-local" version="2.22" transfer-ownership="none"> + <doc xml:space="preserve">Whether this is a site-local multicast address. +See g_inet_address_get_is_mc_site_local().</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="is-multicast" version="2.22" transfer-ownership="none"> + <doc xml:space="preserve">Whether this is a multicast address. +See g_inet_address_get_is_multicast().</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="is-site-local" version="2.22" transfer-ownership="none"> + <doc xml:space="preserve">Whether this is a site-local address. +See g_inet_address_get_is_loopback().</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="InetAddressPrivate" c:type="GInetAddressPrivate*"/> + </field> + </class> + <record name="InetAddressClass" c:type="GInetAddressClass" glib:is-gtype-struct-for="InetAddress"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="to_string"> + <callback name="to_string"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a representation of @address as a string, which should be +freed after use.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="to_bytes"> + <callback name="to_bytes"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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().</doc> + <type name="guint8" c:type="const guint8*"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="InetAddressMask" c:symbol-prefix="inet_address_mask" c:type="GInetAddressMask" version="2.32" parent="GObject.Object" glib:type-name="GInetAddressMask" glib:get-type="g_inet_address_mask_get_type" glib:type-struct="InetAddressMaskClass"> + <doc xml:space="preserve">#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".</doc> + <implements name="Initable"/> + <constructor name="new" c:identifier="g_inet_address_mask_new" version="2.32" throws="1"> + <doc xml:space="preserve">Creates a new #GInetAddressMask representing all addresses whose +first @length bits match @addr.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GInetAddressMask, or %NULL on error</doc> + <type name="InetAddressMask" c:type="GInetAddressMask*"/> + </return-value> + <parameters> + <parameter name="addr" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">number of bits of @addr to use</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_string" c:identifier="g_inet_address_mask_new_from_string" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GInetAddressMask corresponding to @string, or %NULL +on error.</doc> + <type name="InetAddressMask" c:type="GInetAddressMask*"/> + </return-value> + <parameters> + <parameter name="mask_string" transfer-ownership="none"> + <doc xml:space="preserve">an IP address or address/length string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <method name="equal" c:identifier="g_inet_address_mask_equal" version="2.32"> + <doc xml:space="preserve">Tests if @mask and @mask2 are the same mask.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether @mask and @mask2 are the same mask</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mask" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddressMask</doc> + <type name="InetAddressMask" c:type="GInetAddressMask*"/> + </instance-parameter> + <parameter name="mask2" transfer-ownership="none"> + <doc xml:space="preserve">another #GInetAddressMask</doc> + <type name="InetAddressMask" c:type="GInetAddressMask*"/> + </parameter> + </parameters> + </method> + <method name="get_address" c:identifier="g_inet_address_mask_get_address" version="2.32"> + <doc xml:space="preserve">Gets @mask's base address</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@mask's base address</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </return-value> + <parameters> + <instance-parameter name="mask" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddressMask</doc> + <type name="InetAddressMask" c:type="GInetAddressMask*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_family" c:identifier="g_inet_address_mask_get_family" version="2.32"> + <doc xml:space="preserve">Gets the #GSocketFamily of @mask's address</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GSocketFamily of @mask's address</doc> + <type name="SocketFamily" c:type="GSocketFamily"/> + </return-value> + <parameters> + <instance-parameter name="mask" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddressMask</doc> + <type name="InetAddressMask" c:type="GInetAddressMask*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_length" c:identifier="g_inet_address_mask_get_length" version="2.32"> + <doc xml:space="preserve">Gets @mask's length</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@mask's length</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="mask" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddressMask</doc> + <type name="InetAddressMask" c:type="GInetAddressMask*"/> + </instance-parameter> + </parameters> + </method> + <method name="matches" c:identifier="g_inet_address_mask_matches" version="2.32"> + <doc xml:space="preserve">Tests if @address falls within the range described by @mask.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether @address falls within the range described by +@mask.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mask" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddressMask</doc> + <type name="InetAddressMask" c:type="GInetAddressMask*"/> + </instance-parameter> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + </parameters> + </method> + <method name="to_string" c:identifier="g_inet_address_mask_to_string" version="2.32"> + <doc xml:space="preserve">Converts @mask back to its corresponding string form.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a string corresponding to @mask.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="mask" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddressMask</doc> + <type name="InetAddressMask" c:type="GInetAddressMask*"/> + </instance-parameter> + </parameters> + </method> + <property name="address" writable="1" transfer-ownership="none"> + <type name="InetAddress"/> + </property> + <property name="family" transfer-ownership="none"> + <type name="SocketFamily"/> + </property> + <property name="length" writable="1" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="InetAddressMaskPrivate" c:type="GInetAddressMaskPrivate*"/> + </field> + </class> + <record name="InetAddressMaskClass" c:type="GInetAddressMaskClass" glib:is-gtype-struct-for="InetAddressMask"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <record name="InetAddressMaskPrivate" c:type="GInetAddressMaskPrivate" disguised="1"/> + <record name="InetAddressPrivate" c:type="GInetAddressPrivate" disguised="1"/> + <class name="InetSocketAddress" c:symbol-prefix="inet_socket_address" c:type="GInetSocketAddress" parent="SocketAddress" glib:type-name="GInetSocketAddress" glib:get-type="g_inet_socket_address_get_type" glib:type-struct="InetSocketAddressClass"> + <doc xml:space="preserve">An IPv4 or IPv6 socket address; that is, the combination of a +#GInetAddress and a port number.</doc> + <implements name="SocketConnectable"/> + <constructor name="new" c:identifier="g_inet_socket_address_new" version="2.22"> + <doc xml:space="preserve">Creates a new #GInetSocketAddress for @address and @port.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GInetSocketAddress</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + <parameter name="port" transfer-ownership="none"> + <doc xml:space="preserve">a port number</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_string" c:identifier="g_inet_socket_address_new_from_string" version="2.40"> + <doc xml:space="preserve">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 `%`).</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new #GInetSocketAddress, +or %NULL if @address cannot be parsed.</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">the string form of an IP address</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="port" transfer-ownership="none"> + <doc xml:space="preserve">a port number</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </constructor> + <method name="get_address" c:identifier="g_inet_socket_address_get_address" version="2.22"> + <doc xml:space="preserve">Gets @address's #GInetAddress.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GInetAddress for @address, which must be +g_object_ref()'d if it will be stored</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetSocketAddress</doc> + <type name="InetSocketAddress" c:type="GInetSocketAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_flowinfo" c:identifier="g_inet_socket_address_get_flowinfo" version="2.32"> + <doc xml:space="preserve">Gets the `sin6_flowinfo` field from @address, +which must be an IPv6 address.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the flowinfo field</doc> + <type name="guint32" c:type="guint32"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress</doc> + <type name="InetSocketAddress" c:type="GInetSocketAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_port" c:identifier="g_inet_socket_address_get_port" version="2.22"> + <doc xml:space="preserve">Gets @address's port.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the port for @address</doc> + <type name="guint16" c:type="guint16"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetSocketAddress</doc> + <type name="InetSocketAddress" c:type="GInetSocketAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_scope_id" c:identifier="g_inet_socket_address_get_scope_id" version="2.32"> + <doc xml:space="preserve">Gets the `sin6_scope_id` field from @address, +which must be an IPv6 address.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the scope id field</doc> + <type name="guint32" c:type="guint32"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a %G_SOCKET_FAMILY_IPV6 #GInetAddress</doc> + <type name="InetSocketAddress" c:type="GInetSocketAddress*"/> + </instance-parameter> + </parameters> + </method> + <property name="address" writable="1" construct-only="1" transfer-ownership="none"> + <type name="InetAddress"/> + </property> + <property name="flowinfo" version="2.32" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The `sin6_flowinfo` field, for IPv6 addresses.</doc> + <type name="guint" c:type="guint"/> + </property> + <property name="port" writable="1" construct-only="1" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </property> + <property name="scope-id" writable="1" construct-only="1" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </property> + <field name="parent_instance"> + <type name="SocketAddress" c:type="GSocketAddress"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="InetSocketAddressPrivate" c:type="GInetSocketAddressPrivate*"/> + </field> + </class> + <record name="InetSocketAddressClass" c:type="GInetSocketAddressClass" glib:is-gtype-struct-for="InetSocketAddress"> + <field name="parent_class"> + <type name="SocketAddressClass" c:type="GSocketAddressClass"/> + </field> + </record> + <record name="InetSocketAddressPrivate" c:type="GInetSocketAddressPrivate" disguised="1"/> + <interface name="Initable" c:symbol-prefix="initable" c:type="GInitable" version="2.22" glib:type-name="GInitable" glib:get-type="g_initable_get_type" glib:type-struct="InitableIface"> + <doc xml:space="preserve">#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 implementing %GInitable +during normal construction and automatically initialize them, throwing +an exception on failure.</doc> + <function name="new" c:identifier="g_initable_new" version="2.22" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated + #GObject, or %NULL on error</doc> + <type name="GObject.Object" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="object_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType supporting #GInitable.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">a #GError location to store the error occurring, or %NULL to + ignore.</doc> + <type name="GLib.Error" c:type="GError**"/> + </parameter> + <parameter name="first_property_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the name of the first property, or %NULL if no + properties</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the value if the first property, followed by and other property + value pairs, and ended by %NULL.</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="new_valist" c:identifier="g_initable_new_valist" version="2.22" introspectable="0" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated + #GObject, or %NULL on error</doc> + <type name="GObject.Object" c:type="GObject*"/> + </return-value> + <parameters> + <parameter name="object_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType supporting #GInitable.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="first_property_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the first property, followed by +the value, and other property value pairs, and ended by %NULL.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="var_args" transfer-ownership="none"> + <doc xml:space="preserve">The var args list generated from @first_property_name.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="newv" c:identifier="g_initable_newv" version="2.22" deprecated="1" deprecated-version="2.54" throws="1"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_object_new_with_properties() and +g_initable_init() instead. See #GParameter for more information.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated + #GObject, or %NULL on error</doc> + <type name="GObject.Object" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="object_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType supporting #GInitable.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_parameters" transfer-ownership="none"> + <doc xml:space="preserve">the number of parameters in @parameters</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="parameters" transfer-ownership="none"> + <doc xml:space="preserve">the parameters to use to construct the object</doc> + <array length="1" zero-terminated="0" c:type="GParameter*"> + <type name="GObject.Parameter" c:type="GParameter"/> + </array> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <virtual-method name="init" invoker="init" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful. If an error has occurred, this function will + return %FALSE and set @error appropriately if present.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="initable" transfer-ownership="none"> + <doc xml:space="preserve">a #GInitable.</doc> + <type name="Initable" c:type="GInitable*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <method name="init" c:identifier="g_initable_init" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful. If an error has occurred, this function will + return %FALSE and set @error appropriately if present.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="initable" transfer-ownership="none"> + <doc xml:space="preserve">a #GInitable.</doc> + <type name="Initable" c:type="GInitable*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + </interface> + <record name="InitableIface" c:type="GInitableIface" glib:is-gtype-struct-for="Initable" version="2.22"> + <doc xml:space="preserve">Provides an interface for initializing object such that initialization +may fail.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="init"> + <callback name="init" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful. If an error has occurred, this function will + return %FALSE and set @error appropriately if present.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="initable" transfer-ownership="none"> + <doc xml:space="preserve">a #GInitable.</doc> + <type name="Initable" c:type="GInitable*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <record name="InputMessage" c:type="GInputMessage" version="2.48"> + <doc xml:space="preserve">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`.</doc> + <field name="address" writable="1"> + <doc xml:space="preserve">return location + for a #GSocketAddress, or %NULL</doc> + <type name="SocketAddress" c:type="GSocketAddress**"/> + </field> + <field name="vectors" writable="1"> + <doc xml:space="preserve">pointer to an + array of input vectors</doc> + <array length="2" zero-terminated="0" c:type="GInputVector*"> + <type name="InputVector" c:type="GInputVector"/> + </array> + </field> + <field name="num_vectors" writable="1"> + <doc xml:space="preserve">the number of input vectors pointed to by @vectors</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="bytes_received" writable="1"> + <doc xml:space="preserve">will be set to the number of bytes that have been + received</doc> + <type name="gsize" c:type="gsize"/> + </field> + <field name="flags" writable="1"> + <doc xml:space="preserve">collection of #GSocketMsgFlags for the received message, + outputted by the call</doc> + <type name="gint" c:type="gint"/> + </field> + <field name="control_messages" writable="1"> + <doc xml:space="preserve">return location for a + caller-allocated array of #GSocketControlMessages, or %NULL</doc> + <array length="6" zero-terminated="0" c:type="GSocketControlMessage***"> + <type name="SocketControlMessage" c:type="GSocketControlMessage**"/> + </array> + </field> + <field name="num_control_messages" writable="1"> + <doc xml:space="preserve">return location for the number of + elements in @control_messages</doc> + <type name="guint" c:type="guint*"/> + </field> + </record> + <class name="InputStream" c:symbol-prefix="input_stream" c:type="GInputStream" parent="GObject.Object" abstract="1" glib:type-name="GInputStream" glib:get-type="g_input_stream_get_type" glib:type-struct="InputStreamClass"> + <doc xml:space="preserve">#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.</doc> + <virtual-method name="close_async" invoker="close_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="close_finish" invoker="close_finish" throws="1"> + <doc xml:space="preserve">Finishes closing a stream asynchronously, started from g_input_stream_close_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the stream was closed successfully.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="close_fn" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="read_async" invoker="read_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="buffer" direction="out" caller-allocates="1" transfer-ownership="none" nullable="1"> + <doc xml:space="preserve"> + a buffer to read data into (which should be at least count bytes long).</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the number of bytes that will be read from the stream</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] +of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="read_finish" invoker="read_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous stream read operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">number of bytes read in, or -1 on error, or 0 on end of file.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="read_fn" throws="1"> + <return-value transfer-ownership="none"> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="gpointer" c:type="void*"/> + </parameter> + <parameter name="count" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="skip" invoker="skip" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of bytes skipped, or -1 on error</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes that will be skipped from the stream</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="skip_async" invoker="skip_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes that will be skipped from the stream</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="skip_finish" invoker="skip_finish" throws="1"> + <doc xml:space="preserve">Finishes a stream skip operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the size of the bytes skipped, or `-1` on error.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <method name="clear_pending" c:identifier="g_input_stream_clear_pending"> + <doc xml:space="preserve">Clears the pending flag on @stream.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">input stream</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="close" c:identifier="g_input_stream_close" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="close_async" c:identifier="g_input_stream_close_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="close_finish" c:identifier="g_input_stream_close_finish" throws="1"> + <doc xml:space="preserve">Finishes closing a stream asynchronously, started from g_input_stream_close_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the stream was closed successfully.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="has_pending" c:identifier="g_input_stream_has_pending"> + <doc xml:space="preserve">Checks if an input stream has pending actions.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @stream has pending actions.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">input stream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_closed" c:identifier="g_input_stream_is_closed"> + <doc xml:space="preserve">Checks if an input stream is closed.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the stream is closed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">input stream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="read" c:identifier="g_input_stream_read" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of bytes read, or -1 on error, or 0 on end of file.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="buffer" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve"> + a buffer to read data into (which should be at least count bytes long).</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the number of bytes that will be read from the stream</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_all" c:identifier="g_input_stream_read_all" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if there was an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="buffer" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve"> + a buffer to read data into (which should be at least count bytes long).</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the number of bytes that will be read from the stream</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">location to store the number of bytes that was read from the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_all_async" c:identifier="g_input_stream_read_all_async" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GInputStream</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="buffer" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve"> + a buffer to read data into (which should be at least count bytes long)</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the number of bytes that will be read from the stream</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="read_all_finish" c:identifier="g_input_stream_read_all_finish" version="2.44" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if there was an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">location to store the number of bytes that was read from the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="read_async" c:identifier="g_input_stream_read_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="buffer" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve"> + a buffer to read data into (which should be at least count bytes long).</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the number of bytes that will be read from the stream</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] +of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="read_bytes" c:identifier="g_input_stream_read_bytes" version="2.34" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GBytes, or %NULL on error</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">maximum number of bytes that will be read from the stream. Common +values include 4096 and 8192.</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_bytes_async" c:identifier="g_input_stream_read_bytes_async" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes that will be read from the stream</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="read_bytes_finish" c:identifier="g_input_stream_read_bytes_finish" version="2.34" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous stream read-into-#GBytes operation.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the newly-allocated #GBytes, or %NULL on error</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="read_finish" c:identifier="g_input_stream_read_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous stream read operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">number of bytes read in, or -1 on error, or 0 on end of file.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="set_pending" c:identifier="g_input_stream_set_pending" throws="1"> + <doc xml:space="preserve">Sets @stream to have actions pending. If the pending flag is +already set or @stream is closed, it will return %FALSE and set +@error.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if pending was previously unset and is now set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">input stream</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="skip" c:identifier="g_input_stream_skip" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of bytes skipped, or -1 on error</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes that will be skipped from the stream</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="skip_async" c:identifier="g_input_stream_skip_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes that will be skipped from the stream</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="skip_finish" c:identifier="g_input_stream_skip_finish" throws="1"> + <doc xml:space="preserve">Finishes a stream skip operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the size of the bytes skipped, or `-1` on error.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="InputStreamPrivate" c:type="GInputStreamPrivate*"/> + </field> + </class> + <record name="InputStreamClass" c:type="GInputStreamClass" glib:is-gtype-struct-for="InputStream"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="read_fn"> + <callback name="read_fn" throws="1"> + <return-value transfer-ownership="none"> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="buffer" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="gpointer" c:type="void*"/> + </parameter> + <parameter name="count" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="skip"> + <callback name="skip" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of bytes skipped, or -1 on error</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes that will be skipped from the stream</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="close_fn"> + <callback name="close_fn" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="read_async"> + <callback name="read_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="buffer" direction="out" caller-allocates="1" transfer-ownership="none" nullable="1"> + <doc xml:space="preserve"> + a buffer to read data into (which should be at least count bytes long).</doc> + <array length="2" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the number of bytes that will be read from the stream</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] +of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="read_finish"> + <callback name="read_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">number of bytes read in, or -1 on error, or 0 on end of file.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="skip_async"> + <callback name="skip_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes that will be skipped from the stream</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="skip_finish"> + <callback name="skip_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the size of the bytes skipped, or `-1` on error.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="close_async"> + <callback name="close_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="close_finish"> + <callback name="close_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the stream was closed successfully.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="InputStreamPrivate" c:type="GInputStreamPrivate" disguised="1"/> + <record name="InputVector" c:type="GInputVector" version="2.22"> + <doc xml:space="preserve">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.</doc> + <field name="buffer" writable="1"> + <doc xml:space="preserve">Pointer to a buffer where data will be written.</doc> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="size" writable="1"> + <doc xml:space="preserve">the available size in @buffer.</doc> + <type name="gsize" c:type="gsize"/> + </field> + </record> + <function-macro name="LOADABLE_ICON" c:identifier="G_LOADABLE_ICON" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="LOADABLE_ICON_GET_IFACE" c:identifier="G_LOADABLE_ICON_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <interface name="ListModel" c:symbol-prefix="list_model" c:type="GListModel" glib:type-name="GListModel" glib:get-type="g_list_model_get_type" glib:type-struct="ListModelInterface"> + <doc xml:space="preserve">#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 facilitate 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.</doc> + <virtual-method name="get_item" version="2.44"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the object at @position.</doc> + <type name="GObject.Object" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GListModel</doc> + <type name="ListModel" c:type="GListModel*"/> + </instance-parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position of the item to fetch</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_item_type" invoker="get_item_type" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GType of the items contained in @list.</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GListModel</doc> + <type name="ListModel" c:type="GListModel*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_n_items" invoker="get_n_items" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of items in @list.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GListModel</doc> + <type name="ListModel" c:type="GListModel*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="get_item" c:identifier="g_list_model_get_item" shadowed-by="get_object" version="2.44" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the item at @position.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GListModel</doc> + <type name="ListModel" c:type="GListModel*"/> + </instance-parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position of the item to fetch</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="get_item_type" c:identifier="g_list_model_get_item_type" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GType of the items contained in @list.</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GListModel</doc> + <type name="ListModel" c:type="GListModel*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_n_items" c:identifier="g_list_model_get_n_items" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of items in @list.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GListModel</doc> + <type name="ListModel" c:type="GListModel*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_object" c:identifier="g_list_model_get_object" shadows="get_item" version="2.44"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the object at @position.</doc> + <type name="GObject.Object" c:type="GObject*"/> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GListModel</doc> + <type name="ListModel" c:type="GListModel*"/> + </instance-parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position of the item to fetch</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="items_changed" c:identifier="g_list_model_items_changed" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GListModel</doc> + <type name="ListModel" c:type="GListModel*"/> + </instance-parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position at which @list changed</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="removed" transfer-ownership="none"> + <doc xml:space="preserve">the number of items removed</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="added" transfer-ownership="none"> + <doc xml:space="preserve">the number of items added</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <glib:signal name="items-changed" when="last" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position at which @list changed</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="removed" transfer-ownership="none"> + <doc xml:space="preserve">the number of items removed</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="added" transfer-ownership="none"> + <doc xml:space="preserve">the number of items added</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </glib:signal> + </interface> + <record name="ListModelInterface" c:type="GListModelInterface" glib:is-gtype-struct-for="ListModel" version="2.44"> + <doc xml:space="preserve">The virtual function table for #GListModel.</doc> + <field name="g_iface"> + <doc xml:space="preserve">parent #GTypeInterface</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="get_item_type"> + <callback name="get_item_type"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GType of the items contained in @list.</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GListModel</doc> + <type name="ListModel" c:type="GListModel*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_n_items"> + <callback name="get_n_items"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of items in @list.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GListModel</doc> + <type name="ListModel" c:type="GListModel*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_item"> + <callback name="get_item"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the object at @position.</doc> + <type name="GObject.Object" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GListModel</doc> + <type name="ListModel" c:type="GListModel*"/> + </parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position of the item to fetch</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="ListStore" c:symbol-prefix="list_store" c:type="GListStore" parent="GObject.Object" glib:type-name="GListStore" glib:get-type="g_list_store_get_type" glib:type-struct="ListStoreClass"> + <doc xml:space="preserve">#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.</doc> + <implements name="ListModel"/> + <constructor name="new" c:identifier="g_list_store_new" version="2.44"> + <doc xml:space="preserve">Creates a new #GListStore with items of type @item_type. @item_type +must be a subclass of #GObject.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GListStore</doc> + <type name="ListStore" c:type="GListStore*"/> + </return-value> + <parameters> + <parameter name="item_type" transfer-ownership="none"> + <doc xml:space="preserve">the #GType of items in the list</doc> + <type name="GType" c:type="GType"/> + </parameter> + </parameters> + </constructor> + <method name="append" c:identifier="g_list_store_append" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="store" transfer-ownership="none"> + <doc xml:space="preserve">a #GListStore</doc> + <type name="ListStore" c:type="GListStore*"/> + </instance-parameter> + <parameter name="item" transfer-ownership="none"> + <doc xml:space="preserve">the new item</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="find" c:identifier="g_list_store_find" version="2.64"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Whether @store contains @item. If it was found, @position will be +set to the position where @item occurred for the first time.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="store" transfer-ownership="none"> + <doc xml:space="preserve">a #GListStore</doc> + <type name="ListStore" c:type="GListStore*"/> + </instance-parameter> + <parameter name="item" transfer-ownership="none"> + <doc xml:space="preserve">an item</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + <parameter name="position" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the first position of @item, if it was found.</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </method> + <method name="find_with_equal_func" c:identifier="g_list_store_find_with_equal_func" version="2.64"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Whether @store contains @item. If it was found, @position will be +set to the position where @item occurred for the first time.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="store" transfer-ownership="none"> + <doc xml:space="preserve">a #GListStore</doc> + <type name="ListStore" c:type="GListStore*"/> + </instance-parameter> + <parameter name="item" transfer-ownership="none"> + <doc xml:space="preserve">an item</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + <parameter name="equal_func" transfer-ownership="none" scope="call"> + <doc xml:space="preserve">A custom equality check function</doc> + <type name="GLib.EqualFunc" c:type="GEqualFunc"/> + </parameter> + <parameter name="position" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the first position of @item, if it was found.</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </method> + <method name="insert" c:identifier="g_list_store_insert" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="store" transfer-ownership="none"> + <doc xml:space="preserve">a #GListStore</doc> + <type name="ListStore" c:type="GListStore*"/> + </instance-parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position at which to insert the new item</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="item" transfer-ownership="none"> + <doc xml:space="preserve">the new item</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="insert_sorted" c:identifier="g_list_store_insert_sorted" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the position at which @item was inserted</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="store" transfer-ownership="none"> + <doc xml:space="preserve">a #GListStore</doc> + <type name="ListStore" c:type="GListStore*"/> + </instance-parameter> + <parameter name="item" transfer-ownership="none"> + <doc xml:space="preserve">the new item</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + <parameter name="compare_func" transfer-ownership="none" scope="call" closure="2"> + <doc xml:space="preserve">pairwise comparison function for sorting</doc> + <type name="GLib.CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data for @compare_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="remove" c:identifier="g_list_store_remove" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="store" transfer-ownership="none"> + <doc xml:space="preserve">a #GListStore</doc> + <type name="ListStore" c:type="GListStore*"/> + </instance-parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position of the item that is to be removed</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="remove_all" c:identifier="g_list_store_remove_all" version="2.44"> + <doc xml:space="preserve">Removes all items from @store.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="store" transfer-ownership="none"> + <doc xml:space="preserve">a #GListStore</doc> + <type name="ListStore" c:type="GListStore*"/> + </instance-parameter> + </parameters> + </method> + <method name="sort" c:identifier="g_list_store_sort" version="2.46"> + <doc xml:space="preserve">Sort the items in @store according to @compare_func.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="store" transfer-ownership="none"> + <doc xml:space="preserve">a #GListStore</doc> + <type name="ListStore" c:type="GListStore*"/> + </instance-parameter> + <parameter name="compare_func" transfer-ownership="none" scope="call" closure="1"> + <doc xml:space="preserve">pairwise comparison function for sorting</doc> + <type name="GLib.CompareDataFunc" c:type="GCompareDataFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data for @compare_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="splice" c:identifier="g_list_store_splice" version="2.44"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="store" transfer-ownership="none"> + <doc xml:space="preserve">a #GListStore</doc> + <type name="ListStore" c:type="GListStore*"/> + </instance-parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position at which to make the change</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="n_removals" transfer-ownership="none"> + <doc xml:space="preserve">the number of items to remove</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="additions" transfer-ownership="none"> + <doc xml:space="preserve">the items to add</doc> + <array length="3" zero-terminated="0" c:type="gpointer*"> + <type name="GObject.Object"/> + </array> + </parameter> + <parameter name="n_additions" transfer-ownership="none"> + <doc xml:space="preserve">the number of items to add</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <property name="item-type" version="2.44" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The type of items contained in this list store. Items must be +subclasses of #GObject.</doc> + <type name="GType" c:type="GType"/> + </property> + </class> + <record name="ListStoreClass" c:type="GListStoreClass" glib:is-gtype-struct-for="ListStore"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <interface name="LoadableIcon" c:symbol-prefix="loadable_icon" c:type="GLoadableIcon" glib:type-name="GLoadableIcon" glib:get-type="g_loadable_icon_get_type" glib:type-struct="LoadableIconIface"> + <doc xml:space="preserve">Extends the #GIcon interface and adds the ability to +load icons from streams.</doc> + <prerequisite name="Icon"/> + <virtual-method name="load" invoker="load" throws="1"> + <doc xml:space="preserve">Loads a loadable icon. For the asynchronous version of this function, +see g_loadable_icon_load_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GInputStream to read the icon from.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <instance-parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GLoadableIcon.</doc> + <type name="LoadableIcon" c:type="GLoadableIcon*"/> + </instance-parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">an integer.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="type" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to store the type of the loaded +icon, %NULL to ignore.</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to +ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="load_async" invoker="load_async"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GLoadableIcon.</doc> + <type name="LoadableIcon" c:type="GLoadableIcon*"/> + </instance-parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">an integer.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the + request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="load_finish" invoker="load_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous icon load started in g_loadable_icon_load_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GInputStream to read the icon from.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <instance-parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GLoadableIcon.</doc> + <type name="LoadableIcon" c:type="GLoadableIcon*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="type" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to store the type of the loaded + icon, %NULL to ignore.</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </virtual-method> + <method name="load" c:identifier="g_loadable_icon_load" throws="1"> + <doc xml:space="preserve">Loads a loadable icon. For the asynchronous version of this function, +see g_loadable_icon_load_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GInputStream to read the icon from.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <instance-parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GLoadableIcon.</doc> + <type name="LoadableIcon" c:type="GLoadableIcon*"/> + </instance-parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">an integer.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="type" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to store the type of the loaded +icon, %NULL to ignore.</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to +ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="load_async" c:identifier="g_loadable_icon_load_async"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GLoadableIcon.</doc> + <type name="LoadableIcon" c:type="GLoadableIcon*"/> + </instance-parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">an integer.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the + request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="load_finish" c:identifier="g_loadable_icon_load_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous icon load started in g_loadable_icon_load_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GInputStream to read the icon from.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <instance-parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GLoadableIcon.</doc> + <type name="LoadableIcon" c:type="GLoadableIcon*"/> + </instance-parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="type" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to store the type of the loaded + icon, %NULL to ignore.</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + </interface> + <record name="LoadableIconIface" c:type="GLoadableIconIface" glib:is-gtype-struct-for="LoadableIcon"> + <doc xml:space="preserve">Interface for icons that can be loaded as a stream.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="load"> + <callback name="load" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GInputStream to read the icon from.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GLoadableIcon.</doc> + <type name="LoadableIcon" c:type="GLoadableIcon*"/> + </parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">an integer.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="type" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to store the type of the loaded +icon, %NULL to ignore.</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to +ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="load_async"> + <callback name="load_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GLoadableIcon.</doc> + <type name="LoadableIcon" c:type="GLoadableIcon*"/> + </parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">an integer.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the + request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="load_finish"> + <callback name="load_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GInputStream to read the icon from.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GLoadableIcon.</doc> + <type name="LoadableIcon" c:type="GLoadableIcon*"/> + </parameter> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="type" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to store the type of the loaded + icon, %NULL to ignore.</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <function-macro name="MEMORY_INPUT_STREAM" c:identifier="G_MEMORY_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MEMORY_INPUT_STREAM_CLASS" c:identifier="G_MEMORY_INPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MEMORY_INPUT_STREAM_GET_CLASS" c:identifier="G_MEMORY_INPUT_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MEMORY_MONITOR" c:identifier="G_MEMORY_MONITOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <constant name="MEMORY_MONITOR_EXTENSION_POINT_NAME" value="gio-memory-monitor" c:type="G_MEMORY_MONITOR_EXTENSION_POINT_NAME" version="2.64"> + <doc xml:space="preserve">Extension point for memory usage monitoring functionality. +See [Extending GIO][extending-gio].</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="MEMORY_MONITOR_GET_INTERFACE" c:identifier="G_MEMORY_MONITOR_GET_INTERFACE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MEMORY_OUTPUT_STREAM" c:identifier="G_MEMORY_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MEMORY_OUTPUT_STREAM_CLASS" c:identifier="G_MEMORY_OUTPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MEMORY_OUTPUT_STREAM_GET_CLASS" c:identifier="G_MEMORY_OUTPUT_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MENU" c:identifier="G_MENU" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <constant name="MENU_ATTRIBUTE_ACTION" value="action" c:type="G_MENU_ATTRIBUTE_ACTION" version="2.32"> + <doc xml:space="preserve">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().</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="MENU_ATTRIBUTE_ACTION_NAMESPACE" value="action-namespace" c:type="G_MENU_ATTRIBUTE_ACTION_NAMESPACE" version="2.36"> + <doc xml:space="preserve">The menu item attribute that holds the namespace for all action names in +menus that are linked from this item.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="MENU_ATTRIBUTE_ICON" value="icon" c:type="G_MENU_ATTRIBUTE_ICON" version="2.38"> + <doc xml:space="preserve">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).</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="MENU_ATTRIBUTE_ITER" c:identifier="G_MENU_ATTRIBUTE_ITER" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MENU_ATTRIBUTE_ITER_CLASS" c:identifier="G_MENU_ATTRIBUTE_ITER_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MENU_ATTRIBUTE_ITER_GET_CLASS" c:identifier="G_MENU_ATTRIBUTE_ITER_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <constant name="MENU_ATTRIBUTE_LABEL" value="label" c:type="G_MENU_ATTRIBUTE_LABEL" version="2.32"> + <doc xml:space="preserve">The menu item attribute which holds the label of the item.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="MENU_ATTRIBUTE_TARGET" value="target" c:type="G_MENU_ATTRIBUTE_TARGET" version="2.32"> + <doc xml:space="preserve">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()</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="MENU_ITEM" c:identifier="G_MENU_ITEM" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MENU_LINK_ITER" c:identifier="G_MENU_LINK_ITER" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MENU_LINK_ITER_CLASS" c:identifier="G_MENU_LINK_ITER_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MENU_LINK_ITER_GET_CLASS" c:identifier="G_MENU_LINK_ITER_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <constant name="MENU_LINK_SECTION" value="section" c:type="G_MENU_LINK_SECTION" version="2.32"> + <doc xml:space="preserve">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().</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="MENU_LINK_SUBMENU" value="submenu" c:type="G_MENU_LINK_SUBMENU" version="2.32"> + <doc xml:space="preserve">The name of the link that associates a menu item with a submenu. + +See also g_menu_item_set_link().</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="MENU_MODEL" c:identifier="G_MENU_MODEL" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MENU_MODEL_CLASS" c:identifier="G_MENU_MODEL_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MENU_MODEL_GET_CLASS" c:identifier="G_MENU_MODEL_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MOUNT" c:identifier="G_MOUNT" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MOUNT_GET_IFACE" c:identifier="G_MOUNT_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MOUNT_OPERATION" c:identifier="G_MOUNT_OPERATION" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MOUNT_OPERATION_CLASS" c:identifier="G_MOUNT_OPERATION_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MOUNT_OPERATION_GET_CLASS" c:identifier="G_MOUNT_OPERATION_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <class name="MemoryInputStream" c:symbol-prefix="memory_input_stream" c:type="GMemoryInputStream" parent="InputStream" glib:type-name="GMemoryInputStream" glib:get-type="g_memory_input_stream_get_type" glib:type-struct="MemoryInputStreamClass"> + <doc xml:space="preserve">#GMemoryInputStream is a class for using arbitrary +memory chunks as input for GIO streaming input operations. + +As of GLib 2.34, #GMemoryInputStream implements +#GPollableInputStream.</doc> + <implements name="PollableInputStream"/> + <implements name="Seekable"/> + <constructor name="new" c:identifier="g_memory_input_stream_new"> + <doc xml:space="preserve">Creates a new empty #GMemoryInputStream.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GInputStream</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + </constructor> + <constructor name="new_from_bytes" c:identifier="g_memory_input_stream_new_from_bytes" version="2.34"> + <doc xml:space="preserve">Creates a new #GMemoryInputStream with data from the given @bytes.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">new #GInputStream read from @bytes</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <parameter name="bytes" transfer-ownership="none"> + <doc xml:space="preserve">a #GBytes</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_data" c:identifier="g_memory_input_stream_new_from_data"> + <doc xml:space="preserve">Creates a new #GMemoryInputStream with data in memory of a given size.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">new #GInputStream read from @data of @len bytes.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="full"> + <doc xml:space="preserve">input data</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">length of the data, may be -1 if @data is a nul-terminated string</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">function that is called to free @data, or %NULL</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </constructor> + <method name="add_bytes" c:identifier="g_memory_input_stream_add_bytes" version="2.34"> + <doc xml:space="preserve">Appends @bytes to data that can be read from the input stream.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GMemoryInputStream</doc> + <type name="MemoryInputStream" c:type="GMemoryInputStream*"/> + </instance-parameter> + <parameter name="bytes" transfer-ownership="none"> + <doc xml:space="preserve">input data</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + </parameters> + </method> + <method name="add_data" c:identifier="g_memory_input_stream_add_data"> + <doc xml:space="preserve">Appends @data to data that can be read from the input stream</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GMemoryInputStream</doc> + <type name="MemoryInputStream" c:type="GMemoryInputStream*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="full"> + <doc xml:space="preserve">input data</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">length of the data, may be -1 if @data is a nul-terminated string</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">function that is called to free @data, or %NULL</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="InputStream" c:type="GInputStream"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="MemoryInputStreamPrivate" c:type="GMemoryInputStreamPrivate*"/> + </field> + </class> + <record name="MemoryInputStreamClass" c:type="GMemoryInputStreamClass" glib:is-gtype-struct-for="MemoryInputStream"> + <field name="parent_class"> + <type name="InputStreamClass" c:type="GInputStreamClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="MemoryInputStreamPrivate" c:type="GMemoryInputStreamPrivate" disguised="1"/> + <interface name="MemoryMonitor" c:symbol-prefix="memory_monitor" c:type="GMemoryMonitor" version="2.64" glib:type-name="GMemoryMonitor" glib:get-type="g_memory_monitor_get_type" glib:type-struct="MemoryMonitorInterface"> + <doc xml:space="preserve">#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 +- Call [`malloc_trim(3)`](man:malloc_trim) to return cached heap pages to + the kernel (if supported by your libc) + +Note that some actions may not always improve system performance, and so +should be profiled for your application. `malloc_trim()`, for example, may +make future heap allocations slower (due to releasing cached heap pages back +to the kernel). + +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.</doc> + <prerequisite name="Initable"/> + <function name="dup_default" c:identifier="g_memory_monitor_dup_default" version="2.64"> + <doc xml:space="preserve">Gets a reference to the default #GMemoryMonitor for the system.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new reference to the default #GMemoryMonitor</doc> + <type name="MemoryMonitor" c:type="GMemoryMonitor*"/> + </return-value> + </function> + <virtual-method name="low_memory_warning"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <type name="MemoryMonitor" c:type="GMemoryMonitor*"/> + </instance-parameter> + <parameter name="level" transfer-ownership="none"> + <type name="MemoryMonitorWarningLevel" c:type="GMemoryMonitorWarningLevel"/> + </parameter> + </parameters> + </virtual-method> + <glib:signal name="low-memory-warning" when="last" version="2.64"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="level" transfer-ownership="none"> + <doc xml:space="preserve">the #GMemoryMonitorWarningLevel warning level</doc> + <type name="MemoryMonitorWarningLevel"/> + </parameter> + </parameters> + </glib:signal> + </interface> + <record name="MemoryMonitorInterface" c:type="GMemoryMonitorInterface" glib:is-gtype-struct-for="MemoryMonitor" version="2.64"> + <doc xml:space="preserve">The virtual function table for #GMemoryMonitor.</doc> + <field name="g_iface" readable="0" private="1"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="low_memory_warning"> + <callback name="low_memory_warning"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="monitor" transfer-ownership="none"> + <type name="MemoryMonitor" c:type="GMemoryMonitor*"/> + </parameter> + <parameter name="level" transfer-ownership="none"> + <type name="MemoryMonitorWarningLevel" c:type="GMemoryMonitorWarningLevel"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <enumeration name="MemoryMonitorWarningLevel" version="2.64" glib:type-name="GMemoryMonitorWarningLevel" glib:get-type="g_memory_monitor_warning_level_get_type" c:type="GMemoryMonitorWarningLevel"> + <doc xml:space="preserve">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 (); +]|</doc> + <member name="low" value="50" c:identifier="G_MEMORY_MONITOR_WARNING_LEVEL_LOW" glib:nick="low"> + <doc xml:space="preserve">Memory on the device is low, processes + should free up unneeded resources (for example, in-memory caches) so they can + be used elsewhere.</doc> + </member> + <member name="medium" value="100" c:identifier="G_MEMORY_MONITOR_WARNING_LEVEL_MEDIUM" glib:nick="medium"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="critical" value="255" c:identifier="G_MEMORY_MONITOR_WARNING_LEVEL_CRITICAL" glib:nick="critical"> + <doc xml:space="preserve">The system will soon start terminating + processes to reclaim memory, including background processes.</doc> + </member> + </enumeration> + <class name="MemoryOutputStream" c:symbol-prefix="memory_output_stream" c:type="GMemoryOutputStream" parent="OutputStream" glib:type-name="GMemoryOutputStream" glib:get-type="g_memory_output_stream_get_type" glib:type-struct="MemoryOutputStreamClass"> + <doc xml:space="preserve">#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.</doc> + <implements name="PollableOutputStream"/> + <implements name="Seekable"/> + <constructor name="new" c:identifier="g_memory_output_stream_new" introspectable="0"> + <doc xml:space="preserve">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); +]|</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A newly created #GMemoryOutputStream object.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">pointer to a chunk of memory to use, or %NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">the size of @data</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="realloc_function" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" destroy="3"> + <doc xml:space="preserve">a function with realloc() semantics (like g_realloc()) + to be called when @data needs to be grown, or %NULL</doc> + <type name="ReallocFunc" c:type="GReallocFunc"/> + </parameter> + <parameter name="destroy_function" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a function to be called on @data when the stream is + finalized, or %NULL</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_resizable" c:identifier="g_memory_output_stream_new_resizable" version="2.36"> + <doc xml:space="preserve">Creates a new #GMemoryOutputStream, using g_realloc() and g_free() +for memory allocation.</doc> + <return-value transfer-ownership="full"> + <type name="OutputStream" c:type="GOutputStream*"/> + </return-value> + </constructor> + <method name="get_data" c:identifier="g_memory_output_stream_get_data"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">pointer to the stream's data, or %NULL if the data + has been stolen</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="ostream" transfer-ownership="none"> + <doc xml:space="preserve">a #GMemoryOutputStream</doc> + <type name="MemoryOutputStream" c:type="GMemoryOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_data_size" c:identifier="g_memory_output_stream_get_data_size" version="2.18"> + <doc xml:space="preserve">Returns the number of bytes from the start up to including the last +byte written in the stream that has not been truncated away.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes written to the stream</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="ostream" transfer-ownership="none"> + <doc xml:space="preserve">a #GMemoryOutputStream</doc> + <type name="MemoryOutputStream" c:type="GMemoryOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_size" c:identifier="g_memory_output_stream_get_size"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes allocated for the data buffer</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="ostream" transfer-ownership="none"> + <doc xml:space="preserve">a #GMemoryOutputStream</doc> + <type name="MemoryOutputStream" c:type="GMemoryOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="steal_as_bytes" c:identifier="g_memory_output_stream_steal_as_bytes" version="2.34"> + <doc xml:space="preserve">Returns data from the @ostream as a #GBytes. @ostream must be +closed before calling this function.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the stream's data</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <instance-parameter name="ostream" transfer-ownership="none"> + <doc xml:space="preserve">a #GMemoryOutputStream</doc> + <type name="MemoryOutputStream" c:type="GMemoryOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="steal_data" c:identifier="g_memory_output_stream_steal_data" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the stream's data, or %NULL if it has previously + been stolen</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="ostream" transfer-ownership="none"> + <doc xml:space="preserve">a #GMemoryOutputStream</doc> + <type name="MemoryOutputStream" c:type="GMemoryOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <property name="data" version="2.24" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">Pointer to buffer where data will be written.</doc> + <type name="gpointer" c:type="gpointer"/> + </property> + <property name="data-size" version="2.24" transfer-ownership="none"> + <doc xml:space="preserve">Size of data written to the buffer.</doc> + <type name="gulong" c:type="gulong"/> + </property> + <property name="destroy-function" version="2.24" introspectable="0" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">Function called with the buffer as argument when the stream is destroyed.</doc> + <type name="gpointer" c:type="gpointer"/> + </property> + <property name="realloc-function" version="2.24" introspectable="0" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">Function with realloc semantics called to enlarge the buffer.</doc> + <type name="gpointer" c:type="gpointer"/> + </property> + <property name="size" version="2.24" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">Current size of the data buffer.</doc> + <type name="gulong" c:type="gulong"/> + </property> + <field name="parent_instance"> + <type name="OutputStream" c:type="GOutputStream"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="MemoryOutputStreamPrivate" c:type="GMemoryOutputStreamPrivate*"/> + </field> + </class> + <record name="MemoryOutputStreamClass" c:type="GMemoryOutputStreamClass" glib:is-gtype-struct-for="MemoryOutputStream"> + <field name="parent_class"> + <type name="OutputStreamClass" c:type="GOutputStreamClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="MemoryOutputStreamPrivate" c:type="GMemoryOutputStreamPrivate" disguised="1"/> + <class name="Menu" c:symbol-prefix="menu" c:type="GMenu" version="2.32" parent="MenuModel" glib:type-name="GMenu" glib:get-type="g_menu_get_type"> + <doc xml:space="preserve">#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().</doc> + <constructor name="new" c:identifier="g_menu_new" version="2.32"> + <doc xml:space="preserve">Creates a new #GMenu. + +The new menu has no items.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GMenu</doc> + <type name="Menu" c:type="GMenu*"/> + </return-value> + </constructor> + <method name="append" c:identifier="g_menu_append" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenu</doc> + <type name="Menu" c:type="GMenu*"/> + </instance-parameter> + <parameter name="label" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the section label, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="detailed_action" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the detailed action string, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="append_item" c:identifier="g_menu_append_item" version="2.32"> + <doc xml:space="preserve">Appends @item to the end of @menu. + +See g_menu_insert_item() for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenu</doc> + <type name="Menu" c:type="GMenu*"/> + </instance-parameter> + <parameter name="item" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuItem to append</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </parameter> + </parameters> + </method> + <method name="append_section" c:identifier="g_menu_append_section" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenu</doc> + <type name="Menu" c:type="GMenu*"/> + </instance-parameter> + <parameter name="label" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the section label, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="section" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel with the items of the section</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + </parameters> + </method> + <method name="append_submenu" c:identifier="g_menu_append_submenu" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenu</doc> + <type name="Menu" c:type="GMenu*"/> + </instance-parameter> + <parameter name="label" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the section label, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="submenu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel with the items of the submenu</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + </parameters> + </method> + <method name="freeze" c:identifier="g_menu_freeze" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenu</doc> + <type name="Menu" c:type="GMenu*"/> + </instance-parameter> + </parameters> + </method> + <method name="insert" c:identifier="g_menu_insert" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenu</doc> + <type name="Menu" c:type="GMenu*"/> + </instance-parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position at which to insert the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="label" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the section label, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="detailed_action" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the detailed action string, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="insert_item" c:identifier="g_menu_insert_item" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenu</doc> + <type name="Menu" c:type="GMenu*"/> + </instance-parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position at which to insert the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="item" transfer-ownership="none"> + <doc xml:space="preserve">the #GMenuItem to insert</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </parameter> + </parameters> + </method> + <method name="insert_section" c:identifier="g_menu_insert_section" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenu</doc> + <type name="Menu" c:type="GMenu*"/> + </instance-parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position at which to insert the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="label" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the section label, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="section" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel with the items of the section</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + </parameters> + </method> + <method name="insert_submenu" c:identifier="g_menu_insert_submenu" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenu</doc> + <type name="Menu" c:type="GMenu*"/> + </instance-parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position at which to insert the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="label" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the section label, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="submenu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel with the items of the submenu</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + </parameters> + </method> + <method name="prepend" c:identifier="g_menu_prepend" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenu</doc> + <type name="Menu" c:type="GMenu*"/> + </instance-parameter> + <parameter name="label" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the section label, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="detailed_action" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the detailed action string, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="prepend_item" c:identifier="g_menu_prepend_item" version="2.32"> + <doc xml:space="preserve">Prepends @item to the start of @menu. + +See g_menu_insert_item() for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenu</doc> + <type name="Menu" c:type="GMenu*"/> + </instance-parameter> + <parameter name="item" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuItem to prepend</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </parameter> + </parameters> + </method> + <method name="prepend_section" c:identifier="g_menu_prepend_section" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenu</doc> + <type name="Menu" c:type="GMenu*"/> + </instance-parameter> + <parameter name="label" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the section label, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="section" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel with the items of the section</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + </parameters> + </method> + <method name="prepend_submenu" c:identifier="g_menu_prepend_submenu" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenu</doc> + <type name="Menu" c:type="GMenu*"/> + </instance-parameter> + <parameter name="label" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the section label, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="submenu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel with the items of the submenu</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + </parameters> + </method> + <method name="remove" c:identifier="g_menu_remove" version="2.32"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenu</doc> + <type name="Menu" c:type="GMenu*"/> + </instance-parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position of the item to remove</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="remove_all" c:identifier="g_menu_remove_all" version="2.38"> + <doc xml:space="preserve">Removes all items in the menu.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenu</doc> + <type name="Menu" c:type="GMenu*"/> + </instance-parameter> + </parameters> + </method> + </class> + <class name="MenuAttributeIter" c:symbol-prefix="menu_attribute_iter" c:type="GMenuAttributeIter" version="2.32" parent="GObject.Object" abstract="1" glib:type-name="GMenuAttributeIter" glib:get-type="g_menu_attribute_iter_get_type" glib:type-struct="MenuAttributeIterClass"> + <doc xml:space="preserve">#GMenuAttributeIter is an opaque structure type. You must access it +using the functions below.</doc> + <virtual-method name="get_next" invoker="get_next" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, or %FALSE if there is no additional + attribute</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuAttributeIter</doc> + <type name="MenuAttributeIter" c:type="GMenuAttributeIter*"/> + </instance-parameter> + <parameter name="out_name" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">the type of the attribute</doc> + <type name="utf8" c:type="const gchar**"/> + </parameter> + <parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the attribute value</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_name" c:identifier="g_menu_attribute_iter_get_name" version="2.32"> + <doc xml:space="preserve">Gets the name of the attribute at the current iterator position, as +a string. + +The iterator is not advanced.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the name of the attribute</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuAttributeIter</doc> + <type name="MenuAttributeIter" c:type="GMenuAttributeIter*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_next" c:identifier="g_menu_attribute_iter_get_next" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, or %FALSE if there is no additional + attribute</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuAttributeIter</doc> + <type name="MenuAttributeIter" c:type="GMenuAttributeIter*"/> + </instance-parameter> + <parameter name="out_name" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">the type of the attribute</doc> + <type name="utf8" c:type="const gchar**"/> + </parameter> + <parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the attribute value</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + </parameters> + </method> + <method name="get_value" c:identifier="g_menu_attribute_iter_get_value" version="2.32"> + <doc xml:space="preserve">Gets the value of the attribute at the current iterator position. + +The iterator is not advanced.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the value of the current attribute</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuAttributeIter</doc> + <type name="MenuAttributeIter" c:type="GMenuAttributeIter*"/> + </instance-parameter> + </parameters> + </method> + <method name="next" c:identifier="g_menu_attribute_iter_next" version="2.32"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, or %FALSE when there are no more attributes</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuAttributeIter</doc> + <type name="MenuAttributeIter" c:type="GMenuAttributeIter*"/> + </instance-parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv"> + <type name="MenuAttributeIterPrivate" c:type="GMenuAttributeIterPrivate*"/> + </field> + </class> + <record name="MenuAttributeIterClass" c:type="GMenuAttributeIterClass" glib:is-gtype-struct-for="MenuAttributeIter"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="get_next"> + <callback name="get_next"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, or %FALSE if there is no additional + attribute</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuAttributeIter</doc> + <type name="MenuAttributeIter" c:type="GMenuAttributeIter*"/> + </parameter> + <parameter name="out_name" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">the type of the attribute</doc> + <type name="utf8" c:type="const gchar**"/> + </parameter> + <parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the attribute value</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <record name="MenuAttributeIterPrivate" c:type="GMenuAttributeIterPrivate" disguised="1"/> + <class name="MenuItem" c:symbol-prefix="menu_item" c:type="GMenuItem" version="2.32" parent="GObject.Object" glib:type-name="GMenuItem" glib:get-type="g_menu_item_get_type"> + <doc xml:space="preserve">#GMenuItem is an opaque structure type. You must access it using the +functions below.</doc> + <constructor name="new" c:identifier="g_menu_item_new" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GMenuItem</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </return-value> + <parameters> + <parameter name="label" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the section label, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="detailed_action" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the detailed action string, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_model" c:identifier="g_menu_item_new_from_model" version="2.34"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GMenuItem.</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </return-value> + <parameters> + <parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">the index of an item in @model</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_section" c:identifier="g_menu_item_new_section" version="2.32"> + <doc xml:space="preserve">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> +]|</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GMenuItem</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </return-value> + <parameters> + <parameter name="label" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the section label, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="section" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel with the items of the section</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_submenu" c:identifier="g_menu_item_new_submenu" version="2.32"> + <doc xml:space="preserve">Creates a new #GMenuItem representing a submenu. + +This is a convenience API around g_menu_item_new() and +g_menu_item_set_submenu().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GMenuItem</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </return-value> + <parameters> + <parameter name="label" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the section label, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="submenu" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel with the items of the submenu</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + </parameters> + </constructor> + <method name="get_attribute" c:identifier="g_menu_item_get_attribute" version="2.34" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the named attribute was found with the expected + type</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="menu_item" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuItem</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">the attribute name to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="format_string" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">positional parameters, as per @format_string</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="get_attribute_value" c:identifier="g_menu_item_get_attribute_value" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the attribute value, or %NULL</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="menu_item" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuItem</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">the attribute name to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="expected_type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected type of the attribute</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </method> + <method name="get_link" c:identifier="g_menu_item_get_link" version="2.34"> + <doc xml:space="preserve">Queries the named @link on @menu_item.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the link, or %NULL</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </return-value> + <parameters> + <instance-parameter name="menu_item" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuItem</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </instance-parameter> + <parameter name="link" transfer-ownership="none"> + <doc xml:space="preserve">the link name to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_action_and_target" c:identifier="g_menu_item_set_action_and_target" version="2.32" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu_item" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuItem</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </instance-parameter> + <parameter name="action" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the name of the action for this item</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="format_string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a GVariant format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">positional parameters, as per @format_string</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="set_action_and_target_value" c:identifier="g_menu_item_set_action_and_target_value" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu_item" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuItem</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </instance-parameter> + <parameter name="action" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the name of the action for this item</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="target_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant to use as the action target</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="set_attribute" c:identifier="g_menu_item_set_attribute" version="2.32" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu_item" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuItem</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">the attribute to set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="format_string" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant format string, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">positional parameters, as per @format_string</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="set_attribute_value" c:identifier="g_menu_item_set_attribute_value" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu_item" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuItem</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </instance-parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">the attribute to set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant to use as the value, or %NULL</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="set_detailed_action" c:identifier="g_menu_item_set_detailed_action" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu_item" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuItem</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </instance-parameter> + <parameter name="detailed_action" transfer-ownership="none"> + <doc xml:space="preserve">the "detailed" action string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_icon" c:identifier="g_menu_item_set_icon" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu_item" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuItem</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </instance-parameter> + <parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GIcon, or %NULL</doc> + <type name="Icon" c:type="GIcon*"/> + </parameter> + </parameters> + </method> + <method name="set_label" c:identifier="g_menu_item_set_label" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu_item" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuItem</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </instance-parameter> + <parameter name="label" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the label to set, or %NULL to unset</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_link" c:identifier="g_menu_item_set_link" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu_item" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuItem</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </instance-parameter> + <parameter name="link" transfer-ownership="none"> + <doc xml:space="preserve">type of link to establish or unset</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="model" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the #GMenuModel to link to (or %NULL to unset)</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + </parameters> + </method> + <method name="set_section" c:identifier="g_menu_item_set_section" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu_item" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuItem</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </instance-parameter> + <parameter name="section" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMenuModel, or %NULL</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + </parameters> + </method> + <method name="set_submenu" c:identifier="g_menu_item_set_submenu" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="menu_item" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuItem</doc> + <type name="MenuItem" c:type="GMenuItem*"/> + </instance-parameter> + <parameter name="submenu" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMenuModel, or %NULL</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + </parameters> + </method> + </class> + <class name="MenuLinkIter" c:symbol-prefix="menu_link_iter" c:type="GMenuLinkIter" version="2.32" parent="GObject.Object" abstract="1" glib:type-name="GMenuLinkIter" glib:get-type="g_menu_link_iter_get_type" glib:type-struct="MenuLinkIterClass"> + <doc xml:space="preserve">#GMenuLinkIter is an opaque structure type. You must access it using +the functions below.</doc> + <virtual-method name="get_next" invoker="get_next" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, or %FALSE if there is no additional link</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuLinkIter</doc> + <type name="MenuLinkIter" c:type="GMenuLinkIter*"/> + </instance-parameter> + <parameter name="out_link" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">the name of the link</doc> + <type name="utf8" c:type="const gchar**"/> + </parameter> + <parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the linked #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel**"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_name" c:identifier="g_menu_link_iter_get_name" version="2.32"> + <doc xml:space="preserve">Gets the name of the link at the current iterator position. + +The iterator is not advanced.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the type of the link</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuLinkIter</doc> + <type name="MenuLinkIter" c:type="GMenuLinkIter*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_next" c:identifier="g_menu_link_iter_get_next" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, or %FALSE if there is no additional link</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuLinkIter</doc> + <type name="MenuLinkIter" c:type="GMenuLinkIter*"/> + </instance-parameter> + <parameter name="out_link" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">the name of the link</doc> + <type name="utf8" c:type="const gchar**"/> + </parameter> + <parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the linked #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel**"/> + </parameter> + </parameters> + </method> + <method name="get_value" c:identifier="g_menu_link_iter_get_value" version="2.32"> + <doc xml:space="preserve">Gets the linked #GMenuModel at the current iterator position. + +The iterator is not advanced.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the #GMenuModel that is linked to</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuLinkIter</doc> + <type name="MenuLinkIter" c:type="GMenuLinkIter*"/> + </instance-parameter> + </parameters> + </method> + <method name="next" c:identifier="g_menu_link_iter_next" version="2.32"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, or %FALSE when there are no more links</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuLinkIter</doc> + <type name="MenuLinkIter" c:type="GMenuLinkIter*"/> + </instance-parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv"> + <type name="MenuLinkIterPrivate" c:type="GMenuLinkIterPrivate*"/> + </field> + </class> + <record name="MenuLinkIterClass" c:type="GMenuLinkIterClass" glib:is-gtype-struct-for="MenuLinkIter"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="get_next"> + <callback name="get_next"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, or %FALSE if there is no additional link</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuLinkIter</doc> + <type name="MenuLinkIter" c:type="GMenuLinkIter*"/> + </parameter> + <parameter name="out_link" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">the name of the link</doc> + <type name="utf8" c:type="const gchar**"/> + </parameter> + <parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">the linked #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel**"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <record name="MenuLinkIterPrivate" c:type="GMenuLinkIterPrivate" disguised="1"/> + <class name="MenuModel" c:symbol-prefix="menu_model" c:type="GMenuModel" version="2.32" parent="GObject.Object" abstract="1" glib:type-name="GMenuModel" glib:get-type="g_menu_model_get_type" glib:type-struct="MenuModelClass"> + <doc xml:space="preserve">#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.</doc> + <virtual-method name="get_item_attribute_value" invoker="get_item_attribute_value" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the value of the attribute</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </instance-parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">the index of the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">the attribute to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="expected_type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected type of the attribute, or + %NULL</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_item_attributes"> + <doc xml:space="preserve">Gets all the attributes associated with the item in the menu model.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">the #GMenuModel to query</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </instance-parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">The #GMenuItem to query</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="attributes" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">Attributes on the item</doc> + <type name="GLib.HashTable" c:type="GHashTable**"> + <type name="utf8"/> + <type name="GLib.Variant"/> + </type> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_item_link" invoker="get_item_link" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the linked #GMenuModel, or %NULL</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </return-value> + <parameters> + <instance-parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </instance-parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">the index of the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="link" transfer-ownership="none"> + <doc xml:space="preserve">the link to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_item_links"> + <doc xml:space="preserve">Gets all the links associated with the item in the menu model.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">the #GMenuModel to query</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </instance-parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">The #GMenuItem to query</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="links" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">Links from the item</doc> + <type name="GLib.HashTable" c:type="GHashTable**"> + <type name="utf8"/> + <type name="MenuModel"/> + </type> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_n_items" invoker="get_n_items" version="2.32"> + <doc xml:space="preserve">Query the number of items in @model.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of items</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="is_mutable" invoker="is_mutable" version="2.32"> + <doc xml:space="preserve">Queries if @model is mutable. + +An immutable #GMenuModel will never emit the #GMenuModel::items-changed +signal. Consumers of the model may make optimisations accordingly.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the model is mutable (ie: "items-changed" may be + emitted).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="iterate_item_attributes" invoker="iterate_item_attributes" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GMenuAttributeIter</doc> + <type name="MenuAttributeIter" c:type="GMenuAttributeIter*"/> + </return-value> + <parameters> + <instance-parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </instance-parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">the index of the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="iterate_item_links" invoker="iterate_item_links" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GMenuLinkIter</doc> + <type name="MenuLinkIter" c:type="GMenuLinkIter*"/> + </return-value> + <parameters> + <instance-parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </instance-parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">the index of the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_item_attribute" c:identifier="g_menu_model_get_item_attribute" version="2.32" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the named attribute was found with the expected + type</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </instance-parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">the index of the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">the attribute to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="format_string" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">positional parameters, as per @format_string</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="get_item_attribute_value" c:identifier="g_menu_model_get_item_attribute_value" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the value of the attribute</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </instance-parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">the index of the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">the attribute to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="expected_type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected type of the attribute, or + %NULL</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </method> + <method name="get_item_link" c:identifier="g_menu_model_get_item_link" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the linked #GMenuModel, or %NULL</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </return-value> + <parameters> + <instance-parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </instance-parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">the index of the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="link" transfer-ownership="none"> + <doc xml:space="preserve">the link to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_n_items" c:identifier="g_menu_model_get_n_items" version="2.32"> + <doc xml:space="preserve">Query the number of items in @model.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of items</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_mutable" c:identifier="g_menu_model_is_mutable" version="2.32"> + <doc xml:space="preserve">Queries if @model is mutable. + +An immutable #GMenuModel will never emit the #GMenuModel::items-changed +signal. Consumers of the model may make optimisations accordingly.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the model is mutable (ie: "items-changed" may be + emitted).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </instance-parameter> + </parameters> + </method> + <method name="items_changed" c:identifier="g_menu_model_items_changed" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </instance-parameter> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position of the change</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="removed" transfer-ownership="none"> + <doc xml:space="preserve">the number of items removed</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="added" transfer-ownership="none"> + <doc xml:space="preserve">the number of items added</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="iterate_item_attributes" c:identifier="g_menu_model_iterate_item_attributes" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GMenuAttributeIter</doc> + <type name="MenuAttributeIter" c:type="GMenuAttributeIter*"/> + </return-value> + <parameters> + <instance-parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </instance-parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">the index of the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="iterate_item_links" c:identifier="g_menu_model_iterate_item_links" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GMenuLinkIter</doc> + <type name="MenuLinkIter" c:type="GMenuLinkIter*"/> + </return-value> + <parameters> + <instance-parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </instance-parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">the index of the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv"> + <type name="MenuModelPrivate" c:type="GMenuModelPrivate*"/> + </field> + <glib:signal name="items-changed" when="last"> + <doc xml:space="preserve">Emitted when a change has occurred 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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="position" transfer-ownership="none"> + <doc xml:space="preserve">the position of the change</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="removed" transfer-ownership="none"> + <doc xml:space="preserve">the number of items removed</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="added" transfer-ownership="none"> + <doc xml:space="preserve">the number of items added</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="MenuModelClass" c:type="GMenuModelClass" glib:is-gtype-struct-for="MenuModel"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="is_mutable"> + <callback name="is_mutable"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the model is mutable (ie: "items-changed" may be + emitted).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_n_items"> + <callback name="get_n_items"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of items</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_item_attributes"> + <callback name="get_item_attributes"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">the #GMenuModel to query</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">The #GMenuItem to query</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="attributes" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">Attributes on the item</doc> + <type name="GLib.HashTable" c:type="GHashTable**"> + <type name="utf8"/> + <type name="GLib.Variant"/> + </type> + </parameter> + </parameters> + </callback> + </field> + <field name="iterate_item_attributes"> + <callback name="iterate_item_attributes"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GMenuAttributeIter</doc> + <type name="MenuAttributeIter" c:type="GMenuAttributeIter*"/> + </return-value> + <parameters> + <parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">the index of the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_item_attribute_value"> + <callback name="get_item_attribute_value"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the value of the attribute</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">the index of the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="attribute" transfer-ownership="none"> + <doc xml:space="preserve">the attribute to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="expected_type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected type of the attribute, or + %NULL</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_item_links"> + <callback name="get_item_links"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">the #GMenuModel to query</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">The #GMenuItem to query</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="links" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">Links from the item</doc> + <type name="GLib.HashTable" c:type="GHashTable**"> + <type name="utf8"/> + <type name="MenuModel"/> + </type> + </parameter> + </parameters> + </callback> + </field> + <field name="iterate_item_links"> + <callback name="iterate_item_links"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GMenuLinkIter</doc> + <type name="MenuLinkIter" c:type="GMenuLinkIter*"/> + </return-value> + <parameters> + <parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">the index of the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_item_link"> + <callback name="get_item_link"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the linked #GMenuModel, or %NULL</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </return-value> + <parameters> + <parameter name="model" transfer-ownership="none"> + <doc xml:space="preserve">a #GMenuModel</doc> + <type name="MenuModel" c:type="GMenuModel*"/> + </parameter> + <parameter name="item_index" transfer-ownership="none"> + <doc xml:space="preserve">the index of the item</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="link" transfer-ownership="none"> + <doc xml:space="preserve">the link to query</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <record name="MenuModelPrivate" c:type="GMenuModelPrivate" disguised="1"/> + <interface name="Mount" c:symbol-prefix="mount" c:type="GMount" glib:type-name="GMount" glib:get-type="g_mount_get_type" glib:type-struct="MountIface"> + <doc xml:space="preserve">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.</doc> + <virtual-method name="can_eject" invoker="can_eject"> + <doc xml:space="preserve">Checks if @mount can be ejected.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @mount can be ejected.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="can_unmount" invoker="can_unmount"> + <doc xml:space="preserve">Checks if @mount can be unmounted.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @mount can be unmounted.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="eject" invoker="eject" deprecated="1" deprecated-version="2.22"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_mount_eject_with_operation() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="eject_finish" invoker="eject_finish" deprecated="1" deprecated-version="2.22" throws="1"> + <doc xml:space="preserve">Finishes ejecting a mount. If any errors occurred during the operation, +@error will be set to contain the errors and %FALSE will be returned.</doc> + <doc-deprecated xml:space="preserve">Use g_mount_eject_with_operation_finish() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount was successfully ejected. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="eject_with_operation" invoker="eject_with_operation" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="eject_with_operation_finish" invoker="eject_with_operation_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes ejecting a mount. If any errors occurred during the operation, +@error will be set to contain the errors and %FALSE will be returned.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount was successfully ejected. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_default_location" invoker="get_default_location"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile. + The returned object should be unreffed with + g_object_unref() when no longer needed.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_drive" invoker="get_drive"> + <doc xml:space="preserve">Gets the drive for the @mount. + +This is a convenience method for getting the #GVolume and then +using that object to get the #GDrive.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="Drive" c:type="GDrive*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_icon" invoker="get_icon"> + <doc xml:space="preserve">Gets the icon for @mount.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon. + The returned object should be unreffed with + g_object_unref() when no longer needed.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_name" invoker="get_name"> + <doc xml:space="preserve">Gets the name of @mount.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the name for the given @mount. + The returned string should be freed with g_free() + when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_root" invoker="get_root"> + <doc xml:space="preserve">Gets the root directory on @mount.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile. + The returned object should be unreffed with + g_object_unref() when no longer needed.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_sort_key" invoker="get_sort_key" version="2.32"> + <doc xml:space="preserve">Gets the sort key for @mount, if any.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">Sorting key for @mount or %NULL if no such key is available.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">A #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_symbolic_icon" invoker="get_symbolic_icon" version="2.34"> + <doc xml:space="preserve">Gets the symbolic icon for @mount.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon. + The returned object should be unreffed with + g_object_unref() when no longer needed.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_uuid" invoker="get_uuid"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_volume" invoker="get_volume"> + <doc xml:space="preserve">Gets the volume for the @mount.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="Volume" c:type="GVolume*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="guess_content_type" invoker="guess_content_type" version="2.18"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="force_rescan" transfer-ownership="none"> + <doc xml:space="preserve">Whether to force a rescan of the content. + Otherwise a cached result will be used if available</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">user data passed to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="guess_content_type_finish" invoker="guess_content_type_finish" version="2.18" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated array of content types or %NULL on error. + Caller should free this array with g_strfreev() when done with it.</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="guess_content_type_sync" invoker="guess_content_type_sync" version="2.18" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated array of content types or %NULL on error. + Caller should free this array with g_strfreev() when done with it.</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="force_rescan" transfer-ownership="none"> + <doc xml:space="preserve">Whether to force a rescan of the content. + Otherwise a cached result will be used if available</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="pre_unmount"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="remount" invoker="remount"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountMountFlags" c:type="GMountMountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="remount_finish" invoker="remount_finish" throws="1"> + <doc xml:space="preserve">Finishes remounting a mount. If any errors occurred during the operation, +@error will be set to contain the errors and %FALSE will be returned.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount was successfully remounted. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="unmount" invoker="unmount" deprecated="1" deprecated-version="2.22"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_mount_unmount_with_operation() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="unmount_finish" invoker="unmount_finish" deprecated="1" deprecated-version="2.22" throws="1"> + <doc xml:space="preserve">Finishes unmounting a mount. If any errors occurred during the operation, +@error will be set to contain the errors and %FALSE will be returned.</doc> + <doc-deprecated xml:space="preserve">Use g_mount_unmount_with_operation_finish() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount was successfully unmounted. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="unmount_with_operation" invoker="unmount_with_operation" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="unmount_with_operation_finish" invoker="unmount_with_operation_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes unmounting a mount. If any errors occurred during the operation, +@error will be set to contain the errors and %FALSE will be returned.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount was successfully unmounted. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="unmounted"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="can_eject" c:identifier="g_mount_can_eject"> + <doc xml:space="preserve">Checks if @mount can be ejected.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @mount can be ejected.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </method> + <method name="can_unmount" c:identifier="g_mount_can_unmount"> + <doc xml:space="preserve">Checks if @mount can be unmounted.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @mount can be unmounted.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </method> + <method name="eject" c:identifier="g_mount_eject" deprecated="1" deprecated-version="2.22"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_mount_eject_with_operation() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="eject_finish" c:identifier="g_mount_eject_finish" deprecated="1" deprecated-version="2.22" throws="1"> + <doc xml:space="preserve">Finishes ejecting a mount. If any errors occurred during the operation, +@error will be set to contain the errors and %FALSE will be returned.</doc> + <doc-deprecated xml:space="preserve">Use g_mount_eject_with_operation_finish() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount was successfully ejected. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="eject_with_operation" c:identifier="g_mount_eject_with_operation" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="eject_with_operation_finish" c:identifier="g_mount_eject_with_operation_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes ejecting a mount. If any errors occurred during the operation, +@error will be set to contain the errors and %FALSE will be returned.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount was successfully ejected. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="get_default_location" c:identifier="g_mount_get_default_location"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile. + The returned object should be unreffed with + g_object_unref() when no longer needed.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_drive" c:identifier="g_mount_get_drive"> + <doc xml:space="preserve">Gets the drive for the @mount. + +This is a convenience method for getting the #GVolume and then +using that object to get the #GDrive.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="Drive" c:type="GDrive*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_icon" c:identifier="g_mount_get_icon"> + <doc xml:space="preserve">Gets the icon for @mount.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon. + The returned object should be unreffed with + g_object_unref() when no longer needed.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_name" c:identifier="g_mount_get_name"> + <doc xml:space="preserve">Gets the name of @mount.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the name for the given @mount. + The returned string should be freed with g_free() + when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_root" c:identifier="g_mount_get_root"> + <doc xml:space="preserve">Gets the root directory on @mount.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile. + The returned object should be unreffed with + g_object_unref() when no longer needed.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_sort_key" c:identifier="g_mount_get_sort_key" version="2.32"> + <doc xml:space="preserve">Gets the sort key for @mount, if any.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">Sorting key for @mount or %NULL if no such key is available.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">A #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_symbolic_icon" c:identifier="g_mount_get_symbolic_icon" version="2.34"> + <doc xml:space="preserve">Gets the symbolic icon for @mount.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon. + The returned object should be unreffed with + g_object_unref() when no longer needed.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_uuid" c:identifier="g_mount_get_uuid"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_volume" c:identifier="g_mount_get_volume"> + <doc xml:space="preserve">Gets the volume for the @mount.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="Volume" c:type="GVolume*"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </method> + <method name="guess_content_type" c:identifier="g_mount_guess_content_type" version="2.18"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="force_rescan" transfer-ownership="none"> + <doc xml:space="preserve">Whether to force a rescan of the content. + Otherwise a cached result will be used if available</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="guess_content_type_finish" c:identifier="g_mount_guess_content_type_finish" version="2.18" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated array of content types or %NULL on error. + Caller should free this array with g_strfreev() when done with it.</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="guess_content_type_sync" c:identifier="g_mount_guess_content_type_sync" version="2.18" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated array of content types or %NULL on error. + Caller should free this array with g_strfreev() when done with it.</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="force_rescan" transfer-ownership="none"> + <doc xml:space="preserve">Whether to force a rescan of the content. + Otherwise a cached result will be used if available</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="is_shadowed" c:identifier="g_mount_is_shadowed" version="2.20"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @mount is shadowed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">A #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </method> + <method name="remount" c:identifier="g_mount_remount"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountMountFlags" c:type="GMountMountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="remount_finish" c:identifier="g_mount_remount_finish" throws="1"> + <doc xml:space="preserve">Finishes remounting a mount. If any errors occurred during the operation, +@error will be set to contain the errors and %FALSE will be returned.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount was successfully remounted. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="shadow" c:identifier="g_mount_shadow" version="2.20"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">A #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </method> + <method name="unmount" c:identifier="g_mount_unmount" deprecated="1" deprecated-version="2.22"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_mount_unmount_with_operation() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="unmount_finish" c:identifier="g_mount_unmount_finish" deprecated="1" deprecated-version="2.22" throws="1"> + <doc xml:space="preserve">Finishes unmounting a mount. If any errors occurred during the operation, +@error will be set to contain the errors and %FALSE will be returned.</doc> + <doc-deprecated xml:space="preserve">Use g_mount_unmount_with_operation_finish() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount was successfully unmounted. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="unmount_with_operation" c:identifier="g_mount_unmount_with_operation" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="unmount_with_operation_finish" c:identifier="g_mount_unmount_with_operation_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes unmounting a mount. If any errors occurred during the operation, +@error will be set to contain the errors and %FALSE will be returned.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount was successfully unmounted. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="unshadow" c:identifier="g_mount_unshadow" version="2.20"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">A #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </instance-parameter> + </parameters> + </method> + <glib:signal name="changed" when="last"> + <doc xml:space="preserve">Emitted when the mount has been changed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + <glib:signal name="pre-unmount" when="last" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + <glib:signal name="unmounted" when="last"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + </interface> + <record name="MountIface" c:type="GMountIface" glib:is-gtype-struct-for="Mount"> + <doc xml:space="preserve">Interface for implementing operations for mounts.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="changed"> + <callback name="changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="unmounted"> + <callback name="unmounted"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_root"> + <callback name="get_root"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile. + The returned object should be unreffed with + g_object_unref() when no longer needed.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_name"> + <callback name="get_name"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the name for the given @mount. + The returned string should be freed with g_free() + when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_icon"> + <callback name="get_icon"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon. + The returned object should be unreffed with + g_object_unref() when no longer needed.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_uuid"> + <callback name="get_uuid"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_volume"> + <callback name="get_volume"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="Volume" c:type="GVolume*"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_drive"> + <callback name="get_drive"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="Drive" c:type="GDrive*"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_unmount"> + <callback name="can_unmount"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @mount can be unmounted.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_eject"> + <callback name="can_eject"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @mount can be ejected.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="unmount"> + <callback name="unmount"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="unmount_finish"> + <callback name="unmount_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount was successfully unmounted. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject"> + <callback name="eject"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject_finish"> + <callback name="eject_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount was successfully ejected. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="remount"> + <callback name="remount"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountMountFlags" c:type="GMountMountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="remount_finish"> + <callback name="remount_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount was successfully remounted. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="guess_content_type"> + <callback name="guess_content_type"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + <parameter name="force_rescan" transfer-ownership="none"> + <doc xml:space="preserve">Whether to force a rescan of the content. + Otherwise a cached result will be used if available</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data passed to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="guess_content_type_finish"> + <callback name="guess_content_type_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated array of content types or %NULL on error. + Caller should free this array with g_strfreev() when done with it.</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="guess_content_type_sync"> + <callback name="guess_content_type_sync" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated array of content types or %NULL on error. + Caller should free this array with g_strfreev() when done with it.</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + <parameter name="force_rescan" transfer-ownership="none"> + <doc xml:space="preserve">Whether to force a rescan of the content. + Otherwise a cached result will be used if available</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="pre_unmount"> + <callback name="pre_unmount"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="unmount_with_operation"> + <callback name="unmount_with_operation"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="unmount_with_operation_finish"> + <callback name="unmount_with_operation_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount was successfully unmounted. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject_with_operation"> + <callback name="eject_with_operation"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid + user interaction.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject_with_operation_finish"> + <callback name="eject_with_operation_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount was successfully ejected. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_default_location"> + <callback name="get_default_location"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile. + The returned object should be unreffed with + g_object_unref() when no longer needed.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_sort_key"> + <callback name="get_sort_key"> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">Sorting key for @mount or %NULL if no such key is available.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">A #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_symbolic_icon"> + <callback name="get_symbolic_icon"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon. + The returned object should be unreffed with + g_object_unref() when no longer needed.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount.</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <bitfield name="MountMountFlags" glib:type-name="GMountMountFlags" glib:get-type="g_mount_mount_flags_get_type" c:type="GMountMountFlags"> + <doc xml:space="preserve">Flags used when mounting a mount.</doc> + <member name="none" value="0" c:identifier="G_MOUNT_MOUNT_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + </bitfield> + <class name="MountOperation" c:symbol-prefix="mount_operation" c:type="GMountOperation" parent="GObject.Object" glib:type-name="GMountOperation" glib:get-type="g_mount_operation_get_type" glib:type-struct="MountOperationClass"> + <doc xml:space="preserve">#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.</doc> + <constructor name="new" c:identifier="g_mount_operation_new"> + <doc xml:space="preserve">Creates a new mount operation.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </return-value> + </constructor> + <virtual-method name="aborted"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="ask_password"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + <parameter name="message" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="default_user" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="default_domain" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <type name="AskPasswordFlags" c:type="GAskPasswordFlags"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="ask_question"> + <doc xml:space="preserve">Virtual implementation of #GMountOperation::ask-question.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">string containing a message to display to the user</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="choices" transfer-ownership="none"> + <doc xml:space="preserve">an array of + strings for each possible choice</doc> + <array c:type="const char**"> + <type name="utf8"/> + </array> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="reply" invoker="reply"> + <doc xml:space="preserve">Emits the #GMountOperation::reply signal.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperationResult</doc> + <type name="MountOperationResult" c:type="GMountOperationResult"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="show_processes" version="2.22"> + <doc xml:space="preserve">Virtual implementation of #GMountOperation::show-processes.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">string containing a message to display to the user</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="processes" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GPid for processes blocking + the operation</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="GLib.Pid"/> + </array> + </parameter> + <parameter name="choices" transfer-ownership="none"> + <doc xml:space="preserve">an array of + strings for each possible choice</doc> + <array c:type="const gchar**"> + <type name="utf8"/> + </array> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="show_unmount_progress"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + <parameter name="message" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="time_left" transfer-ownership="none"> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="bytes_left" transfer-ownership="none"> + <type name="gint64" c:type="gint64"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_anonymous" c:identifier="g_mount_operation_get_anonymous"> + <doc xml:space="preserve">Check to see whether the mount operation is being used +for an anonymous user.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if mount operation is anonymous.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_choice" c:identifier="g_mount_operation_get_choice"> + <doc xml:space="preserve">Gets a choice from the mount operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an integer containing an index of the user's choice from +the choice's list, or `0`.</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_domain" c:identifier="g_mount_operation_get_domain"> + <doc xml:space="preserve">Gets the domain of the mount operation.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string set to the domain.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_tcrypt_hidden_volume" c:identifier="g_mount_operation_get_is_tcrypt_hidden_volume" version="2.58"> + <doc xml:space="preserve">Check to see whether the mount operation is being used +for a TCRYPT hidden volume.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if mount operation is for hidden volume.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_tcrypt_system_volume" c:identifier="g_mount_operation_get_is_tcrypt_system_volume" version="2.58"> + <doc xml:space="preserve">Check to see whether the mount operation is being used +for a TCRYPT system volume.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if mount operation is for system volume.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_password" c:identifier="g_mount_operation_get_password"> + <doc xml:space="preserve">Gets a password from the mount operation.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing the password within @op.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_password_save" c:identifier="g_mount_operation_get_password_save"> + <doc xml:space="preserve">Gets the state of saving passwords for the mount operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GPasswordSave flag.</doc> + <type name="PasswordSave" c:type="GPasswordSave"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_pim" c:identifier="g_mount_operation_get_pim" version="2.58"> + <doc xml:space="preserve">Gets a PIM from the mount operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The VeraCrypt PIM within @op.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_username" c:identifier="g_mount_operation_get_username"> + <doc xml:space="preserve">Get the user name from the mount operation.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing the user name.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + </parameters> + </method> + <method name="reply" c:identifier="g_mount_operation_reply"> + <doc xml:space="preserve">Emits the #GMountOperation::reply signal.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperationResult</doc> + <type name="MountOperationResult" c:type="GMountOperationResult"/> + </parameter> + </parameters> + </method> + <method name="set_anonymous" c:identifier="g_mount_operation_set_anonymous"> + <doc xml:space="preserve">Sets the mount operation to use an anonymous user if @anonymous is %TRUE.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + <parameter name="anonymous" transfer-ownership="none"> + <doc xml:space="preserve">boolean value.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_choice" c:identifier="g_mount_operation_set_choice"> + <doc xml:space="preserve">Sets a default choice for the mount operation.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + <parameter name="choice" transfer-ownership="none"> + <doc xml:space="preserve">an integer.</doc> + <type name="gint" c:type="int"/> + </parameter> + </parameters> + </method> + <method name="set_domain" c:identifier="g_mount_operation_set_domain"> + <doc xml:space="preserve">Sets the mount operation's domain.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + <parameter name="domain" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the domain to set.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_is_tcrypt_hidden_volume" c:identifier="g_mount_operation_set_is_tcrypt_hidden_volume" version="2.58"> + <doc xml:space="preserve">Sets the mount operation to use a hidden volume if @hidden_volume is %TRUE.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + <parameter name="hidden_volume" transfer-ownership="none"> + <doc xml:space="preserve">boolean value.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_is_tcrypt_system_volume" c:identifier="g_mount_operation_set_is_tcrypt_system_volume" version="2.58"> + <doc xml:space="preserve">Sets the mount operation to use a system volume if @system_volume is %TRUE.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + <parameter name="system_volume" transfer-ownership="none"> + <doc xml:space="preserve">boolean value.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_password" c:identifier="g_mount_operation_set_password"> + <doc xml:space="preserve">Sets the mount operation's password to @password.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + <parameter name="password" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">password to set.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_password_save" c:identifier="g_mount_operation_set_password_save"> + <doc xml:space="preserve">Sets the state of saving passwords for the mount operation.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + <parameter name="save" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GPasswordSave flags.</doc> + <type name="PasswordSave" c:type="GPasswordSave"/> + </parameter> + </parameters> + </method> + <method name="set_pim" c:identifier="g_mount_operation_set_pim" version="2.58"> + <doc xml:space="preserve">Sets the mount operation's PIM to @pim.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + <parameter name="pim" transfer-ownership="none"> + <doc xml:space="preserve">an unsigned integer.</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="set_username" c:identifier="g_mount_operation_set_username"> + <doc xml:space="preserve">Sets the user name within @op to @username.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation.</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </instance-parameter> + <parameter name="username" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">input username.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <property name="anonymous" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">Whether to use an anonymous user when authenticating.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="choice" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">The index of the user's choice when a question is asked during the +mount operation. See the #GMountOperation::ask-question signal.</doc> + <type name="gint" c:type="gint"/> + </property> + <property name="domain" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">The domain to use for the mount operation.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="is-tcrypt-hidden-volume" version="2.58" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">Whether the device to be unlocked is a TCRYPT hidden volume. +See [the VeraCrypt documentation](https://www.veracrypt.fr/en/Hidden%20Volume.html).</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="is-tcrypt-system-volume" version="2.58" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">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).</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="password" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">The password that is used for authentication when carrying out +the mount operation.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="password-save" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">Determines if and how the password information should be saved.</doc> + <type name="PasswordSave"/> + </property> + <property name="pim" version="2.58" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">The VeraCrypt PIM value, when unlocking a VeraCrypt volume. See +[the VeraCrypt documentation](https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20(PIM).html).</doc> + <type name="guint" c:type="guint"/> + </property> + <property name="username" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">The user name that is used for authentication when carrying out +the mount operation.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv"> + <type name="MountOperationPrivate" c:type="GMountOperationPrivate*"/> + </field> + <glib:signal name="aborted" when="last" version="2.20"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + <glib:signal name="ask-password" when="last"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">string containing a message to display to the user.</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="default_user" transfer-ownership="none"> + <doc xml:space="preserve">string containing the default user name.</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="default_domain" transfer-ownership="none"> + <doc xml:space="preserve">string containing the default domain.</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GAskPasswordFlags.</doc> + <type name="AskPasswordFlags"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="ask-question" when="last"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">string containing a message to display to the user.</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="choices" transfer-ownership="none"> + <doc xml:space="preserve">an array of strings for each possible choice.</doc> + <array> + <type name="utf8"/> + </array> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="reply" when="last"> + <doc xml:space="preserve">Emitted when the user has replied to the mount operation.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperationResult indicating how the request was handled</doc> + <type name="MountOperationResult"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="show-processes" when="last" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">string containing a message to display to the user.</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="processes" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GPid for processes + blocking the operation.</doc> + <array name="GLib.Array"> + <type name="GLib.Pid"/> + </array> + </parameter> + <parameter name="choices" transfer-ownership="none"> + <doc xml:space="preserve">an array of strings for each possible choice.</doc> + <array> + <type name="utf8"/> + </array> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="show-unmount-progress" when="last" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">string containing a message to display to the user</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="time_left" transfer-ownership="none"> + <doc xml:space="preserve">the estimated time left before the operation completes, + in microseconds, or -1</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="bytes_left" transfer-ownership="none"> + <doc xml:space="preserve">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</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="MountOperationClass" c:type="GMountOperationClass" glib:is-gtype-struct-for="MountOperation"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="ask_password"> + <callback name="ask_password"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="op" transfer-ownership="none"> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="message" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="default_user" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="default_domain" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <type name="AskPasswordFlags" c:type="GAskPasswordFlags"/> + </parameter> + </parameters> + </callback> + </field> + <field name="ask_question"> + <callback name="ask_question"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">string containing a message to display to the user</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="choices" transfer-ownership="none"> + <doc xml:space="preserve">an array of + strings for each possible choice</doc> + <array c:type="const char**"> + <type name="utf8"/> + </array> + </parameter> + </parameters> + </callback> + </field> + <field name="reply"> + <callback name="reply"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperationResult</doc> + <type name="MountOperationResult" c:type="GMountOperationResult"/> + </parameter> + </parameters> + </callback> + </field> + <field name="aborted"> + <callback name="aborted"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="op" transfer-ownership="none"> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="show_processes"> + <callback name="show_processes"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="op" transfer-ownership="none"> + <doc xml:space="preserve">a #GMountOperation</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">string containing a message to display to the user</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="processes" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GPid for processes blocking + the operation</doc> + <array name="GLib.Array" c:type="GArray*"> + <type name="GLib.Pid"/> + </array> + </parameter> + <parameter name="choices" transfer-ownership="none"> + <doc xml:space="preserve">an array of + strings for each possible choice</doc> + <array c:type="const gchar**"> + <type name="utf8"/> + </array> + </parameter> + </parameters> + </callback> + </field> + <field name="show_unmount_progress"> + <callback name="show_unmount_progress"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="op" transfer-ownership="none"> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="message" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="time_left" transfer-ownership="none"> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="bytes_left" transfer-ownership="none"> + <type name="gint64" c:type="gint64"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved6" introspectable="0"> + <callback name="_g_reserved6"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved7" introspectable="0"> + <callback name="_g_reserved7"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved8" introspectable="0"> + <callback name="_g_reserved8"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved9" introspectable="0"> + <callback name="_g_reserved9"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="MountOperationPrivate" c:type="GMountOperationPrivate" disguised="1"/> + <enumeration name="MountOperationResult" glib:type-name="GMountOperationResult" glib:get-type="g_mount_operation_result_get_type" c:type="GMountOperationResult"> + <doc xml:space="preserve">#GMountOperationResult is returned as a result when a request for +information is send by the mounting operation.</doc> + <member name="handled" value="0" c:identifier="G_MOUNT_OPERATION_HANDLED" glib:nick="handled"> + <doc xml:space="preserve">The request was fulfilled and the + user specified data is now available</doc> + </member> + <member name="aborted" value="1" c:identifier="G_MOUNT_OPERATION_ABORTED" glib:nick="aborted"> + <doc xml:space="preserve">The user requested the mount operation + to be aborted</doc> + </member> + <member name="unhandled" value="2" c:identifier="G_MOUNT_OPERATION_UNHANDLED" glib:nick="unhandled"> + <doc xml:space="preserve">The request was unhandled (i.e. not + implemented)</doc> + </member> + </enumeration> + <bitfield name="MountUnmountFlags" glib:type-name="GMountUnmountFlags" glib:get-type="g_mount_unmount_flags_get_type" c:type="GMountUnmountFlags"> + <doc xml:space="preserve">Flags used when an unmounting a mount.</doc> + <member name="none" value="0" c:identifier="G_MOUNT_UNMOUNT_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="force" value="1" c:identifier="G_MOUNT_UNMOUNT_FORCE" glib:nick="force"> + <doc xml:space="preserve">Unmount even if there are outstanding + file operations on the mount.</doc> + </member> + </bitfield> + <function-macro name="NATIVE_SOCKET_ADDRESS" c:identifier="G_NATIVE_SOCKET_ADDRESS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="NATIVE_SOCKET_ADDRESS_CLASS" c:identifier="G_NATIVE_SOCKET_ADDRESS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="NATIVE_SOCKET_ADDRESS_GET_CLASS" c:identifier="G_NATIVE_SOCKET_ADDRESS_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="NATIVE_VOLUME_MONITOR" c:identifier="G_NATIVE_VOLUME_MONITOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="NATIVE_VOLUME_MONITOR_CLASS" c:identifier="G_NATIVE_VOLUME_MONITOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <constant name="NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME" value="gio-native-volume-monitor" c:type="G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME"> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="NETWORK_ADDRESS" c:identifier="G_NETWORK_ADDRESS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="NETWORK_ADDRESS_CLASS" c:identifier="G_NETWORK_ADDRESS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="NETWORK_ADDRESS_GET_CLASS" c:identifier="G_NETWORK_ADDRESS_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="NETWORK_MONITOR" c:identifier="G_NETWORK_MONITOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <constant name="NETWORK_MONITOR_EXTENSION_POINT_NAME" value="gio-network-monitor" c:type="G_NETWORK_MONITOR_EXTENSION_POINT_NAME" version="2.30"> + <doc xml:space="preserve">Extension point for network status monitoring functionality. +See [Extending GIO][extending-gio].</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="NETWORK_MONITOR_GET_INTERFACE" c:identifier="G_NETWORK_MONITOR_GET_INTERFACE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="NETWORK_SERVICE" c:identifier="G_NETWORK_SERVICE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="NETWORK_SERVICE_CLASS" c:identifier="G_NETWORK_SERVICE_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="NETWORK_SERVICE_GET_CLASS" c:identifier="G_NETWORK_SERVICE_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="NOTIFICATION" c:identifier="G_NOTIFICATION" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <class name="NativeSocketAddress" c:symbol-prefix="native_socket_address" c:type="GNativeSocketAddress" parent="SocketAddress" glib:type-name="GNativeSocketAddress" glib:get-type="g_native_socket_address_get_type" glib:type-struct="NativeSocketAddressClass"> + <doc xml:space="preserve">A socket address of some unknown native type.</doc> + <implements name="SocketConnectable"/> + <constructor name="new" c:identifier="g_native_socket_address_new" version="2.46"> + <doc xml:space="preserve">Creates a new #GNativeSocketAddress for @native and @len.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GNativeSocketAddress</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <parameter name="native" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a native address object</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the length of @native, in bytes</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </constructor> + <field name="parent_instance"> + <type name="SocketAddress" c:type="GSocketAddress"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="NativeSocketAddressPrivate" c:type="GNativeSocketAddressPrivate*"/> + </field> + </class> + <record name="NativeSocketAddressClass" c:type="GNativeSocketAddressClass" glib:is-gtype-struct-for="NativeSocketAddress"> + <field name="parent_class"> + <type name="SocketAddressClass" c:type="GSocketAddressClass"/> + </field> + </record> + <record name="NativeSocketAddressPrivate" c:type="GNativeSocketAddressPrivate" disguised="1"/> + <class name="NativeVolumeMonitor" c:symbol-prefix="native_volume_monitor" c:type="GNativeVolumeMonitor" parent="VolumeMonitor" abstract="1" glib:type-name="GNativeVolumeMonitor" glib:get-type="g_native_volume_monitor_get_type" glib:type-struct="NativeVolumeMonitorClass"> + <field name="parent_instance"> + <type name="VolumeMonitor" c:type="GVolumeMonitor"/> + </field> + </class> + <record name="NativeVolumeMonitorClass" c:type="GNativeVolumeMonitorClass" glib:is-gtype-struct-for="NativeVolumeMonitor"> + <field name="parent_class"> + <type name="VolumeMonitorClass" c:type="GVolumeMonitorClass"/> + </field> + <field name="get_mount_for_mount_path" introspectable="0"> + <callback name="get_mount_for_mount_path" introspectable="0"> + <return-value> + <type name="Mount" c:type="GMount*"/> + </return-value> + <parameters> + <parameter name="mount_path" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="NetworkAddress" c:symbol-prefix="network_address" c:type="GNetworkAddress" parent="GObject.Object" glib:type-name="GNetworkAddress" glib:get-type="g_network_address_get_type" glib:type-struct="NetworkAddressClass"> + <doc xml:space="preserve">#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.</doc> + <implements name="SocketConnectable"/> + <constructor name="new" c:identifier="g_network_address_new" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new #GNetworkAddress</doc> + <type name="NetworkAddress" c:type="GSocketConnectable*"/> + </return-value> + <parameters> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">the hostname</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="port" transfer-ownership="none"> + <doc xml:space="preserve">the port</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_loopback" c:identifier="g_network_address_new_loopback" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new #GNetworkAddress</doc> + <type name="NetworkAddress" c:type="GSocketConnectable*"/> + </return-value> + <parameters> + <parameter name="port" transfer-ownership="none"> + <doc xml:space="preserve">the port</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + </parameters> + </constructor> + <function name="parse" c:identifier="g_network_address_parse" version="2.22" throws="1"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new + #GNetworkAddress, or %NULL on error</doc> + <type name="NetworkAddress" c:type="GSocketConnectable*"/> + </return-value> + <parameters> + <parameter name="host_and_port" transfer-ownership="none"> + <doc xml:space="preserve">the hostname and optionally a port</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="default_port" transfer-ownership="none"> + <doc xml:space="preserve">the default port if not in @host_and_port</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + </parameters> + </function> + <function name="parse_uri" c:identifier="g_network_address_parse_uri" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new + #GNetworkAddress, or %NULL on error</doc> + <type name="NetworkAddress" c:type="GSocketConnectable*"/> + </return-value> + <parameters> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">the hostname and optionally a port</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="default_port" transfer-ownership="none"> + <doc xml:space="preserve">The default port if none is found in the URI</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + </parameters> + </function> + <method name="get_hostname" c:identifier="g_network_address_get_hostname" version="2.22"> + <doc xml:space="preserve">Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded, +depending on what @addr was created with.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@addr's hostname</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="addr" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkAddress</doc> + <type name="NetworkAddress" c:type="GNetworkAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_port" c:identifier="g_network_address_get_port" version="2.22"> + <doc xml:space="preserve">Gets @addr's port number</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@addr's port (which may be 0)</doc> + <type name="guint16" c:type="guint16"/> + </return-value> + <parameters> + <instance-parameter name="addr" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkAddress</doc> + <type name="NetworkAddress" c:type="GNetworkAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_scheme" c:identifier="g_network_address_get_scheme" version="2.26"> + <doc xml:space="preserve">Gets @addr's scheme</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">@addr's scheme (%NULL if not built from URI)</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="addr" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkAddress</doc> + <type name="NetworkAddress" c:type="GNetworkAddress*"/> + </instance-parameter> + </parameters> + </method> + <property name="hostname" writable="1" construct-only="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="port" writable="1" construct-only="1" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </property> + <property name="scheme" writable="1" construct-only="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="NetworkAddressPrivate" c:type="GNetworkAddressPrivate*"/> + </field> + </class> + <record name="NetworkAddressClass" c:type="GNetworkAddressClass" glib:is-gtype-struct-for="NetworkAddress"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <record name="NetworkAddressPrivate" c:type="GNetworkAddressPrivate" disguised="1"/> + <enumeration name="NetworkConnectivity" version="2.44" glib:type-name="GNetworkConnectivity" glib:get-type="g_network_connectivity_get_type" c:type="GNetworkConnectivity"> + <doc xml:space="preserve">The host's network connectivity state, as reported by #GNetworkMonitor.</doc> + <member name="local" value="1" c:identifier="G_NETWORK_CONNECTIVITY_LOCAL" glib:nick="local"> + <doc xml:space="preserve">The host is not configured with a + route to the Internet; it may or may not be connected to a local + network.</doc> + </member> + <member name="limited" value="2" c:identifier="G_NETWORK_CONNECTIVITY_LIMITED" glib:nick="limited"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="portal" value="3" c:identifier="G_NETWORK_CONNECTIVITY_PORTAL" glib:nick="portal"> + <doc xml:space="preserve">The host is behind a captive portal and + cannot reach the full Internet.</doc> + </member> + <member name="full" value="4" c:identifier="G_NETWORK_CONNECTIVITY_FULL" glib:nick="full"> + <doc xml:space="preserve">The host is connected to a network, and + appears to be able to reach the full Internet.</doc> + </member> + </enumeration> + <interface name="NetworkMonitor" c:symbol-prefix="network_monitor" c:type="GNetworkMonitor" version="2.32" glib:type-name="GNetworkMonitor" glib:get-type="g_network_monitor_get_type" glib:type-struct="NetworkMonitorInterface"> + <doc xml:space="preserve">#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.</doc> + <prerequisite name="Initable"/> + <function name="get_default" c:identifier="g_network_monitor_get_default" version="2.32"> + <doc xml:space="preserve">Gets the default #GNetworkMonitor for the system.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkMonitor, which will be + a dummy object if no network monitor is available</doc> + <type name="NetworkMonitor" c:type="GNetworkMonitor*"/> + </return-value> + </function> + <virtual-method name="can_reach" invoker="can_reach" version="2.32" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @connectable is reachable, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkMonitor</doc> + <type name="NetworkMonitor" c:type="GNetworkMonitor*"/> + </instance-parameter> + <parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="can_reach_async" invoker="can_reach_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkMonitor</doc> + <type name="NetworkMonitor" c:type="GNetworkMonitor*"/> + </instance-parameter> + <parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the + request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="can_reach_finish" invoker="can_reach_finish" throws="1"> + <doc xml:space="preserve">Finishes an async network connectivity test. +See g_network_monitor_can_reach_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if network is reachable, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkMonitor</doc> + <type name="NetworkMonitor" c:type="GNetworkMonitor*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="network_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <type name="NetworkMonitor" c:type="GNetworkMonitor*"/> + </instance-parameter> + <parameter name="network_available" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </virtual-method> + <method name="can_reach" c:identifier="g_network_monitor_can_reach" version="2.32" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @connectable is reachable, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkMonitor</doc> + <type name="NetworkMonitor" c:type="GNetworkMonitor*"/> + </instance-parameter> + <parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="can_reach_async" c:identifier="g_network_monitor_can_reach_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkMonitor</doc> + <type name="NetworkMonitor" c:type="GNetworkMonitor*"/> + </instance-parameter> + <parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the + request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="can_reach_finish" c:identifier="g_network_monitor_can_reach_finish" throws="1"> + <doc xml:space="preserve">Finishes an async network connectivity test. +See g_network_monitor_can_reach_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if network is reachable, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkMonitor</doc> + <type name="NetworkMonitor" c:type="GNetworkMonitor*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="get_connectivity" c:identifier="g_network_monitor_get_connectivity" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the network connectivity state</doc> + <type name="NetworkConnectivity" c:type="GNetworkConnectivity"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">the #GNetworkMonitor</doc> + <type name="NetworkMonitor" c:type="GNetworkMonitor*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_network_available" c:identifier="g_network_monitor_get_network_available" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether the network is available</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">the #GNetworkMonitor</doc> + <type name="NetworkMonitor" c:type="GNetworkMonitor*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_network_metered" c:identifier="g_network_monitor_get_network_metered" version="2.46"> + <doc xml:space="preserve">Checks if the network is metered. +See #GNetworkMonitor:network-metered for more details.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether the connection is metered</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">the #GNetworkMonitor</doc> + <type name="NetworkMonitor" c:type="GNetworkMonitor*"/> + </instance-parameter> + </parameters> + </method> + <property name="connectivity" version="2.44" transfer-ownership="none"> + <doc xml:space="preserve">More detailed information about the host's network connectivity. +See g_network_monitor_get_connectivity() and +#GNetworkConnectivity for more details.</doc> + <type name="NetworkConnectivity"/> + </property> + <property name="network-available" version="2.32" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="network-metered" version="2.46" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <glib:signal name="network-changed" when="last" version="2.32"> + <doc xml:space="preserve">Emitted when the network configuration changes.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="network_available" transfer-ownership="none"> + <doc xml:space="preserve">the current value of #GNetworkMonitor:network-available</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </glib:signal> + </interface> + <record name="NetworkMonitorInterface" c:type="GNetworkMonitorInterface" glib:is-gtype-struct-for="NetworkMonitor" version="2.32"> + <doc xml:space="preserve">The virtual function table for #GNetworkMonitor.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="network_changed"> + <callback name="network_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="monitor" transfer-ownership="none"> + <type name="NetworkMonitor" c:type="GNetworkMonitor*"/> + </parameter> + <parameter name="network_available" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_reach"> + <callback name="can_reach" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @connectable is reachable, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkMonitor</doc> + <type name="NetworkMonitor" c:type="GNetworkMonitor*"/> + </parameter> + <parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_reach_async"> + <callback name="can_reach_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkMonitor</doc> + <type name="NetworkMonitor" c:type="GNetworkMonitor*"/> + </parameter> + <parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the + request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_reach_finish"> + <callback name="can_reach_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if network is reachable, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkMonitor</doc> + <type name="NetworkMonitor" c:type="GNetworkMonitor*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="NetworkService" c:symbol-prefix="network_service" c:type="GNetworkService" parent="GObject.Object" glib:type-name="GNetworkService" glib:get-type="g_network_service_get_type" glib:type-struct="NetworkServiceClass"> + <doc xml:space="preserve">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.</doc> + <implements name="SocketConnectable"/> + <constructor name="new" c:identifier="g_network_service_new" version="2.22"> + <doc xml:space="preserve">Creates a new #GNetworkService representing the given @service, +@protocol, and @domain. This will initially be unresolved; use the +#GSocketConnectable interface to resolve it.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GNetworkService</doc> + <type name="NetworkService" c:type="GSocketConnectable*"/> + </return-value> + <parameters> + <parameter name="service" transfer-ownership="none"> + <doc xml:space="preserve">the service type to look up (eg, "ldap")</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="protocol" transfer-ownership="none"> + <doc xml:space="preserve">the networking protocol to use for @service (eg, "tcp")</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">the DNS domain to look up the service in</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <method name="get_domain" c:identifier="g_network_service_get_domain" version="2.22"> + <doc xml:space="preserve">Gets the domain that @srv serves. This might be either UTF-8 or +ASCII-encoded, depending on what @srv was created with.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@srv's domain name</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="srv" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkService</doc> + <type name="NetworkService" c:type="GNetworkService*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_protocol" c:identifier="g_network_service_get_protocol" version="2.22"> + <doc xml:space="preserve">Gets @srv's protocol name (eg, "tcp").</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@srv's protocol name</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="srv" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkService</doc> + <type name="NetworkService" c:type="GNetworkService*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_scheme" c:identifier="g_network_service_get_scheme" version="2.26"> + <doc xml:space="preserve">Gets the URI scheme used to resolve proxies. By default, the service name +is used as scheme.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@srv's scheme name</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="srv" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkService</doc> + <type name="NetworkService" c:type="GNetworkService*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_service" c:identifier="g_network_service_get_service" version="2.22"> + <doc xml:space="preserve">Gets @srv's service name (eg, "ldap").</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@srv's service name</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="srv" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkService</doc> + <type name="NetworkService" c:type="GNetworkService*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_scheme" c:identifier="g_network_service_set_scheme" version="2.26"> + <doc xml:space="preserve">Set's the URI scheme used to resolve proxies. By default, the service name +is used as scheme.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="srv" transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkService</doc> + <type name="NetworkService" c:type="GNetworkService*"/> + </instance-parameter> + <parameter name="scheme" transfer-ownership="none"> + <doc xml:space="preserve">a URI scheme</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <property name="domain" writable="1" construct-only="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="protocol" writable="1" construct-only="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="scheme" writable="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="service" writable="1" construct-only="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="NetworkServicePrivate" c:type="GNetworkServicePrivate*"/> + </field> + </class> + <record name="NetworkServiceClass" c:type="GNetworkServiceClass" glib:is-gtype-struct-for="NetworkService"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <record name="NetworkServicePrivate" c:type="GNetworkServicePrivate" disguised="1"/> + <class name="Notification" c:symbol-prefix="notification" c:type="GNotification" version="2.40" parent="GObject.Object" glib:type-name="GNotification" glib:get-type="g_notification_get_type"> + <doc xml:space="preserve">#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().</doc> + <constructor name="new" c:identifier="g_notification_new" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GNotification instance</doc> + <type name="Notification" c:type="GNotification*"/> + </return-value> + <parameters> + <parameter name="title" transfer-ownership="none"> + <doc xml:space="preserve">the title of the notification</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <method name="add_button" c:identifier="g_notification_add_button" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="notification" transfer-ownership="none"> + <doc xml:space="preserve">a #GNotification</doc> + <type name="Notification" c:type="GNotification*"/> + </instance-parameter> + <parameter name="label" transfer-ownership="none"> + <doc xml:space="preserve">label of the button</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="detailed_action" transfer-ownership="none"> + <doc xml:space="preserve">a detailed action name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="add_button_with_target" c:identifier="g_notification_add_button_with_target" shadowed-by="add_button_with_target_value" version="2.40" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="notification" transfer-ownership="none"> + <doc xml:space="preserve">a #GNotification</doc> + <type name="Notification" c:type="GNotification*"/> + </instance-parameter> + <parameter name="label" transfer-ownership="none"> + <doc xml:space="preserve">label of the button</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">an action name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="target_format" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant format string, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">positional parameters, as determined by @target_format</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="add_button_with_target_value" c:identifier="g_notification_add_button_with_target_value" shadows="add_button_with_target" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="notification" transfer-ownership="none"> + <doc xml:space="preserve">a #GNotification</doc> + <type name="Notification" c:type="GNotification*"/> + </instance-parameter> + <parameter name="label" transfer-ownership="none"> + <doc xml:space="preserve">label of the button</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">an action name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="target" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant to use as @action's parameter, or %NULL</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="set_body" c:identifier="g_notification_set_body" version="2.40"> + <doc xml:space="preserve">Sets the body of @notification to @body.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="notification" transfer-ownership="none"> + <doc xml:space="preserve">a #GNotification</doc> + <type name="Notification" c:type="GNotification*"/> + </instance-parameter> + <parameter name="body" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the new body for @notification, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_default_action" c:identifier="g_notification_set_default_action" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="notification" transfer-ownership="none"> + <doc xml:space="preserve">a #GNotification</doc> + <type name="Notification" c:type="GNotification*"/> + </instance-parameter> + <parameter name="detailed_action" transfer-ownership="none"> + <doc xml:space="preserve">a detailed action name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_default_action_and_target" c:identifier="g_notification_set_default_action_and_target" shadowed-by="set_default_action_and_target_value" version="2.40" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="notification" transfer-ownership="none"> + <doc xml:space="preserve">a #GNotification</doc> + <type name="Notification" c:type="GNotification*"/> + </instance-parameter> + <parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">an action name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="target_format" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant format string, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">positional parameters, as determined by @target_format</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="set_default_action_and_target_value" c:identifier="g_notification_set_default_action_and_target_value" shadows="set_default_action_and_target" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="notification" transfer-ownership="none"> + <doc xml:space="preserve">a #GNotification</doc> + <type name="Notification" c:type="GNotification*"/> + </instance-parameter> + <parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">an action name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="target" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant to use as @action's parameter, or %NULL</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="set_icon" c:identifier="g_notification_set_icon" version="2.40"> + <doc xml:space="preserve">Sets the icon of @notification to @icon.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="notification" transfer-ownership="none"> + <doc xml:space="preserve">a #GNotification</doc> + <type name="Notification" c:type="GNotification*"/> + </instance-parameter> + <parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">the icon to be shown in @notification, as a #GIcon</doc> + <type name="Icon" c:type="GIcon*"/> + </parameter> + </parameters> + </method> + <method name="set_priority" c:identifier="g_notification_set_priority"> + <doc xml:space="preserve">Sets the priority of @notification to @priority. See +#GNotificationPriority for possible values.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="notification" transfer-ownership="none"> + <doc xml:space="preserve">a #GNotification</doc> + <type name="Notification" c:type="GNotification*"/> + </instance-parameter> + <parameter name="priority" transfer-ownership="none"> + <doc xml:space="preserve">a #GNotificationPriority</doc> + <type name="NotificationPriority" c:type="GNotificationPriority"/> + </parameter> + </parameters> + </method> + <method name="set_title" c:identifier="g_notification_set_title" version="2.40"> + <doc xml:space="preserve">Sets the title of @notification to @title.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="notification" transfer-ownership="none"> + <doc xml:space="preserve">a #GNotification</doc> + <type name="Notification" c:type="GNotification*"/> + </instance-parameter> + <parameter name="title" transfer-ownership="none"> + <doc xml:space="preserve">the new title for @notification</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_urgent" c:identifier="g_notification_set_urgent" version="2.40" deprecated="1" deprecated-version="2.42"> + <doc xml:space="preserve">Deprecated in favor of g_notification_set_priority().</doc> + <doc-deprecated xml:space="preserve">Since 2.42, this has been deprecated in favour of + g_notification_set_priority().</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="notification" transfer-ownership="none"> + <doc xml:space="preserve">a #GNotification</doc> + <type name="Notification" c:type="GNotification*"/> + </instance-parameter> + <parameter name="urgent" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @notification is urgent</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + </class> + <enumeration name="NotificationPriority" version="2.42" glib:type-name="GNotificationPriority" glib:get-type="g_notification_priority_get_type" c:type="GNotificationPriority"> + <doc xml:space="preserve">Priority levels for #GNotifications.</doc> + <member name="normal" value="0" c:identifier="G_NOTIFICATION_PRIORITY_NORMAL" glib:nick="normal"> + <doc xml:space="preserve">the default priority, to be used for the + majority of notifications (for example email messages, software updates, + completed download/sync operations)</doc> + </member> + <member name="low" value="1" c:identifier="G_NOTIFICATION_PRIORITY_LOW" glib:nick="low"> + <doc xml:space="preserve">for notifications that do not require + immediate attention - typically used for contextual background + information, such as contact birthdays or local weather</doc> + </member> + <member name="high" value="2" c:identifier="G_NOTIFICATION_PRIORITY_HIGH" glib:nick="high"> + <doc xml:space="preserve">for events that require more attention, + usually because responses are time-sensitive (for example chat and SMS + messages or alarms)</doc> + </member> + <member name="urgent" value="3" c:identifier="G_NOTIFICATION_PRIORITY_URGENT" glib:nick="urgent"> + <doc xml:space="preserve">for urgent notifications, or notifications + that require a response in a short space of time (for example phone calls + or emergency warnings)</doc> + </member> + </enumeration> + <function-macro name="OUTPUT_STREAM" c:identifier="G_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="OUTPUT_STREAM_CLASS" c:identifier="G_OUTPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="OUTPUT_STREAM_GET_CLASS" c:identifier="G_OUTPUT_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <record name="OutputMessage" c:type="GOutputMessage" version="2.44"> + <doc xml:space="preserve">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()).</doc> + <field name="address" writable="1"> + <doc xml:space="preserve">a #GSocketAddress, or %NULL</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </field> + <field name="vectors" writable="1"> + <doc xml:space="preserve">pointer to an array of output vectors</doc> + <type name="OutputVector" c:type="GOutputVector*"/> + </field> + <field name="num_vectors" writable="1"> + <doc xml:space="preserve">the number of output vectors pointed to by @vectors.</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="bytes_sent" writable="1"> + <doc xml:space="preserve">initialize to 0. Will be set to the number of bytes + that have been sent</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="control_messages" writable="1"> + <doc xml:space="preserve">a pointer + to an array of #GSocketControlMessages, or %NULL.</doc> + <array length="5" zero-terminated="0" c:type="GSocketControlMessage**"> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </array> + </field> + <field name="num_control_messages" writable="1"> + <doc xml:space="preserve">number of elements in @control_messages.</doc> + <type name="guint" c:type="guint"/> + </field> + </record> + <class name="OutputStream" c:symbol-prefix="output_stream" c:type="GOutputStream" parent="GObject.Object" abstract="1" glib:type-name="GOutputStream" glib:get-type="g_output_stream_get_type" glib:type-struct="OutputStreamClass"> + <doc xml:space="preserve">#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.</doc> + <virtual-method name="close_async" invoker="close_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="close_finish" invoker="close_finish" throws="1"> + <doc xml:space="preserve">Closes an output stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if stream was successfully closed, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="close_fn" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="flush" invoker="flush" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="flush_async" invoker="flush_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="flush_finish" invoker="flush_finish" throws="1"> + <doc xml:space="preserve">Finishes flushing an output stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if flush operation succeeded, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="splice" invoker="splice" throws="1"> + <doc xml:space="preserve">Splices an input stream into an output stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GOutputStreamSpliceFlags.</doc> + <type name="OutputStreamSpliceFlags" c:type="GOutputStreamSpliceFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="splice_async" invoker="splice_async"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GOutputStreamSpliceFlags.</doc> + <type name="OutputStreamSpliceFlags" c:type="GOutputStreamSpliceFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="splice_finish" invoker="splice_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous stream splice operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="write_async" invoker="write_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the buffer containing the data to write.</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="write_finish" invoker="write_finish" throws="1"> + <doc xml:space="preserve">Finishes a stream write operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #gssize containing the number of bytes written to the stream.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="write_fn" invoker="write" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of bytes written, or -1 on error</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the buffer containing the data to write.</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="writev_async" invoker="writev_async" version="2.60"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="vectors" transfer-ownership="none"> + <doc xml:space="preserve">the buffer containing the #GOutputVectors to write.</doc> + <array length="1" zero-terminated="0" c:type="const GOutputVector*"> + <type name="OutputVector" c:type="GOutputVector"/> + </array> + </parameter> + <parameter name="n_vectors" transfer-ownership="none"> + <doc xml:space="preserve">the number of vectors to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the I/O priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="writev_finish" invoker="writev_finish" version="2.60" throws="1"> + <doc xml:space="preserve">Finishes a stream writev operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if there was an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the number of bytes that were written to the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="writev_fn" invoker="writev" version="2.60" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if there was an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="vectors" transfer-ownership="none"> + <doc xml:space="preserve">the buffer containing the #GOutputVectors to write.</doc> + <array length="1" zero-terminated="0" c:type="const GOutputVector*"> + <type name="OutputVector" c:type="GOutputVector"/> + </array> + </parameter> + <parameter name="n_vectors" transfer-ownership="none"> + <doc xml:space="preserve">the number of vectors to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the number of bytes that were + written to the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <method name="clear_pending" c:identifier="g_output_stream_clear_pending"> + <doc xml:space="preserve">Clears the pending flag on @stream.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">output stream</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="close" c:identifier="g_output_stream_close" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="close_async" c:identifier="g_output_stream_close_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="close_finish" c:identifier="g_output_stream_close_finish" throws="1"> + <doc xml:space="preserve">Closes an output stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if stream was successfully closed, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="flush" c:identifier="g_output_stream_flush" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="flush_async" c:identifier="g_output_stream_flush_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="flush_finish" c:identifier="g_output_stream_flush_finish" throws="1"> + <doc xml:space="preserve">Finishes flushing an output stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if flush operation succeeded, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="has_pending" c:identifier="g_output_stream_has_pending"> + <doc xml:space="preserve">Checks if an output stream has pending actions.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @stream has pending actions.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_closed" c:identifier="g_output_stream_is_closed"> + <doc xml:space="preserve">Checks if an output stream has already been closed.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @stream is closed. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_closing" c:identifier="g_output_stream_is_closing" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @stream is being closed. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="printf" c:identifier="g_output_stream_printf" version="2.40" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if there was an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the number of bytes that was + written to the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">location to store the error occurring, or %NULL to ignore</doc> + <type name="GLib.Error" c:type="GError**"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">the format string. See the printf() documentation</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">the parameters to insert into the format string</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="set_pending" c:identifier="g_output_stream_set_pending" throws="1"> + <doc xml:space="preserve">Sets @stream to have actions pending. If the pending flag is +already set or @stream is closed, it will return %FALSE and set +@error.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if pending was previously unset and is now set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="splice" c:identifier="g_output_stream_splice" throws="1"> + <doc xml:space="preserve">Splices an input stream into an output stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GOutputStreamSpliceFlags.</doc> + <type name="OutputStreamSpliceFlags" c:type="GOutputStreamSpliceFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="splice_async" c:identifier="g_output_stream_splice_async"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GOutputStreamSpliceFlags.</doc> + <type name="OutputStreamSpliceFlags" c:type="GOutputStreamSpliceFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="splice_finish" c:identifier="g_output_stream_splice_finish" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous stream splice operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="vprintf" c:identifier="g_output_stream_vprintf" version="2.40" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if there was an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the number of bytes that was + written to the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">location to store the error occurring, or %NULL to ignore</doc> + <type name="GLib.Error" c:type="GError**"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">the format string. See the printf() documentation</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">the parameters to insert into the format string</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </method> + <method name="write" c:identifier="g_output_stream_write" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of bytes written, or -1 on error</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">the buffer containing the data to write.</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_all" c:identifier="g_output_stream_write_all" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if there was an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">the buffer containing the data to write.</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the number of bytes that was + written to the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_all_async" c:identifier="g_output_stream_write_all_async" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GOutputStream</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">the buffer containing the data to write</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="write_all_finish" c:identifier="g_output_stream_write_all_finish" version="2.44" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if there was an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the number of bytes that was written to the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="write_async" c:identifier="g_output_stream_write_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">the buffer containing the data to write.</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="write_bytes" c:identifier="g_output_stream_write_bytes" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of bytes written, or -1 on error</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="bytes" transfer-ownership="none"> + <doc xml:space="preserve">the #GBytes to write</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_bytes_async" c:identifier="g_output_stream_write_bytes_async"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="bytes" transfer-ownership="none"> + <doc xml:space="preserve">The bytes to write</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="write_bytes_finish" c:identifier="g_output_stream_write_bytes_finish" throws="1"> + <doc xml:space="preserve">Finishes a stream write-from-#GBytes operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #gssize containing the number of bytes written to the stream.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="write_finish" c:identifier="g_output_stream_write_finish" throws="1"> + <doc xml:space="preserve">Finishes a stream write operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #gssize containing the number of bytes written to the stream.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="writev" c:identifier="g_output_stream_writev" version="2.60" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if there was an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="vectors" transfer-ownership="none"> + <doc xml:space="preserve">the buffer containing the #GOutputVectors to write.</doc> + <array length="1" zero-terminated="0" c:type="const GOutputVector*"> + <type name="OutputVector" c:type="GOutputVector"/> + </array> + </parameter> + <parameter name="n_vectors" transfer-ownership="none"> + <doc xml:space="preserve">the number of vectors to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the number of bytes that were + written to the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="writev_all" c:identifier="g_output_stream_writev_all" version="2.60" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if there was an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="vectors" transfer-ownership="none"> + <doc xml:space="preserve">the buffer containing the #GOutputVectors to write.</doc> + <array length="1" zero-terminated="0" c:type="GOutputVector*"> + <type name="OutputVector" c:type="GOutputVector"/> + </array> + </parameter> + <parameter name="n_vectors" transfer-ownership="none"> + <doc xml:space="preserve">the number of vectors to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the number of bytes that were + written to the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="writev_all_async" c:identifier="g_output_stream_writev_all_async" version="2.60"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GOutputStream</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="vectors" transfer-ownership="none"> + <doc xml:space="preserve">the buffer containing the #GOutputVectors to write.</doc> + <array length="1" zero-terminated="0" c:type="GOutputVector*"> + <type name="OutputVector" c:type="GOutputVector"/> + </array> + </parameter> + <parameter name="n_vectors" transfer-ownership="none"> + <doc xml:space="preserve">the number of vectors to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the I/O priority of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="writev_all_finish" c:identifier="g_output_stream_writev_all_finish" version="2.60" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if there was an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the number of bytes that were written to the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="writev_async" c:identifier="g_output_stream_writev_async" version="2.60"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="vectors" transfer-ownership="none"> + <doc xml:space="preserve">the buffer containing the #GOutputVectors to write.</doc> + <array length="1" zero-terminated="0" c:type="const GOutputVector*"> + <type name="OutputVector" c:type="GOutputVector"/> + </array> + </parameter> + <parameter name="n_vectors" transfer-ownership="none"> + <doc xml:space="preserve">the number of vectors to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the I/O priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="writev_finish" c:identifier="g_output_stream_writev_finish" version="2.60" throws="1"> + <doc xml:space="preserve">Finishes a stream writev operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if there was an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the number of bytes that were written to the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="OutputStreamPrivate" c:type="GOutputStreamPrivate*"/> + </field> + </class> + <record name="OutputStreamClass" c:type="GOutputStreamClass" glib:is-gtype-struct-for="OutputStream"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="write_fn"> + <callback name="write_fn" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of bytes written, or -1 on error</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="buffer" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the buffer containing the data to write.</doc> + <array length="2" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="splice"> + <callback name="splice" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GOutputStreamSpliceFlags.</doc> + <type name="OutputStreamSpliceFlags" c:type="GOutputStreamSpliceFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="flush"> + <callback name="flush" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="close_fn"> + <callback name="close_fn" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="write_async"> + <callback name="write_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="buffer" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the buffer containing the data to write.</doc> + <array length="2" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="write_finish"> + <callback name="write_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #gssize containing the number of bytes written to the stream.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="splice_async"> + <callback name="splice_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of #GOutputStreamSpliceFlags.</doc> + <type name="OutputStreamSpliceFlags" c:type="GOutputStreamSpliceFlags"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">a #GAsyncReadyCallback.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="splice_finish"> + <callback name="splice_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="flush_async"> + <callback name="flush_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="flush_finish"> + <callback name="flush_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if flush operation succeeded, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="close_async"> + <callback name="close_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="close_finish"> + <callback name="close_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if stream was successfully closed, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="writev_fn"> + <callback name="writev_fn" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if there was an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="vectors" transfer-ownership="none"> + <doc xml:space="preserve">the buffer containing the #GOutputVectors to write.</doc> + <array length="2" zero-terminated="0" c:type="const GOutputVector*"> + <type name="OutputVector" c:type="GOutputVector"/> + </array> + </parameter> + <parameter name="n_vectors" transfer-ownership="none"> + <doc xml:space="preserve">the number of vectors to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the number of bytes that were + written to the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional cancellable object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="writev_async"> + <callback name="writev_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">A #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="vectors" transfer-ownership="none"> + <doc xml:space="preserve">the buffer containing the #GOutputVectors to write.</doc> + <array length="2" zero-terminated="0" c:type="const GOutputVector*"> + <type name="OutputVector" c:type="GOutputVector"/> + </array> + </parameter> + <parameter name="n_vectors" transfer-ownership="none"> + <doc xml:space="preserve">the number of vectors to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the I/O priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">callback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="writev_finish"> + <callback name="writev_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if there was an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the number of bytes that were written to the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved6" introspectable="0"> + <callback name="_g_reserved6"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved7" introspectable="0"> + <callback name="_g_reserved7"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved8" introspectable="0"> + <callback name="_g_reserved8"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="OutputStreamPrivate" c:type="GOutputStreamPrivate" disguised="1"/> + <bitfield name="OutputStreamSpliceFlags" glib:type-name="GOutputStreamSpliceFlags" glib:get-type="g_output_stream_splice_flags_get_type" c:type="GOutputStreamSpliceFlags"> + <doc xml:space="preserve">GOutputStreamSpliceFlags determine how streams should be spliced.</doc> + <member name="none" value="0" c:identifier="G_OUTPUT_STREAM_SPLICE_NONE" glib:nick="none"> + <doc xml:space="preserve">Do not close either stream.</doc> + </member> + <member name="close_source" value="1" c:identifier="G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE" glib:nick="close-source"> + <doc xml:space="preserve">Close the source stream after + the splice.</doc> + </member> + <member name="close_target" value="2" c:identifier="G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET" glib:nick="close-target"> + <doc xml:space="preserve">Close the target stream after + the splice.</doc> + </member> + </bitfield> + <record name="OutputVector" c:type="GOutputVector" version="2.22"> + <doc xml:space="preserve">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.</doc> + <field name="buffer" writable="1"> + <doc xml:space="preserve">Pointer to a buffer of data to read.</doc> + <type name="gpointer" c:type="gconstpointer"/> + </field> + <field name="size" writable="1"> + <doc xml:space="preserve">the size of @buffer.</doc> + <type name="gsize" c:type="gsize"/> + </field> + </record> + <function-macro name="PERMISSION" c:identifier="G_PERMISSION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="PERMISSION_CLASS" c:identifier="G_PERMISSION_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="PERMISSION_GET_CLASS" c:identifier="G_PERMISSION_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="POLLABLE_INPUT_STREAM" c:identifier="G_POLLABLE_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="POLLABLE_INPUT_STREAM_GET_INTERFACE" c:identifier="G_POLLABLE_INPUT_STREAM_GET_INTERFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="POLLABLE_OUTPUT_STREAM" c:identifier="G_POLLABLE_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="POLLABLE_OUTPUT_STREAM_GET_INTERFACE" c:identifier="G_POLLABLE_OUTPUT_STREAM_GET_INTERFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="PROPERTY_ACTION" c:identifier="G_PROPERTY_ACTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="PROXY" c:identifier="G_PROXY" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="PROXY_ADDRESS" c:identifier="G_PROXY_ADDRESS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="PROXY_ADDRESS_CLASS" c:identifier="G_PROXY_ADDRESS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="PROXY_ADDRESS_ENUMERATOR" c:identifier="G_PROXY_ADDRESS_ENUMERATOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="PROXY_ADDRESS_ENUMERATOR_CLASS" c:identifier="G_PROXY_ADDRESS_ENUMERATOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="PROXY_ADDRESS_ENUMERATOR_GET_CLASS" c:identifier="G_PROXY_ADDRESS_ENUMERATOR_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="PROXY_ADDRESS_GET_CLASS" c:identifier="G_PROXY_ADDRESS_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <constant name="PROXY_EXTENSION_POINT_NAME" value="gio-proxy" c:type="G_PROXY_EXTENSION_POINT_NAME" version="2.26"> + <doc xml:space="preserve">Extension point for proxy functionality. +See [Extending GIO][extending-gio].</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="PROXY_GET_IFACE" c:identifier="G_PROXY_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="PROXY_RESOLVER" c:identifier="G_PROXY_RESOLVER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <constant name="PROXY_RESOLVER_EXTENSION_POINT_NAME" value="gio-proxy-resolver" c:type="G_PROXY_RESOLVER_EXTENSION_POINT_NAME"> + <doc xml:space="preserve">Extension point for proxy resolving functionality. +See [Extending GIO][extending-gio].</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="PROXY_RESOLVER_GET_IFACE" c:identifier="G_PROXY_RESOLVER_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <enumeration name="PasswordSave" glib:type-name="GPasswordSave" glib:get-type="g_password_save_get_type" c:type="GPasswordSave"> + <doc xml:space="preserve">#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.</doc> + <member name="never" value="0" c:identifier="G_PASSWORD_SAVE_NEVER" glib:nick="never"> + <doc xml:space="preserve">never save a password.</doc> + </member> + <member name="for_session" value="1" c:identifier="G_PASSWORD_SAVE_FOR_SESSION" glib:nick="for-session"> + <doc xml:space="preserve">save a password for the session.</doc> + </member> + <member name="permanently" value="2" c:identifier="G_PASSWORD_SAVE_PERMANENTLY" glib:nick="permanently"> + <doc xml:space="preserve">save a password permanently.</doc> + </member> + </enumeration> + <class name="Permission" c:symbol-prefix="permission" c:type="GPermission" parent="GObject.Object" abstract="1" glib:type-name="GPermission" glib:get-type="g_permission_get_type" glib:type-struct="PermissionClass"> + <doc xml:space="preserve">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.</doc> + <virtual-method name="acquire" invoker="acquire" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the permission was successfully acquired</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="acquire_async" invoker="acquire_async" version="2.26"> + <doc xml:space="preserve">Attempts to acquire the permission represented by @permission. + +This is the first half of the asynchronous version of +g_permission_acquire().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">the #GAsyncReadyCallback to call when done</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">the user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="acquire_finish" invoker="acquire_finish" version="2.26" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the permission was successfully acquired</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult given to the #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="release" invoker="release" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the permission was successfully released</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="release_async" invoker="release_async" version="2.26"> + <doc xml:space="preserve">Attempts to release the permission represented by @permission. + +This is the first half of the asynchronous version of +g_permission_release().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">the #GAsyncReadyCallback to call when done</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">the user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="release_finish" invoker="release_finish" version="2.26" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the permission was successfully released</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult given to the #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <method name="acquire" c:identifier="g_permission_acquire" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the permission was successfully acquired</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="acquire_async" c:identifier="g_permission_acquire_async" version="2.26"> + <doc xml:space="preserve">Attempts to acquire the permission represented by @permission. + +This is the first half of the asynchronous version of +g_permission_acquire().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">the #GAsyncReadyCallback to call when done</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="acquire_finish" c:identifier="g_permission_acquire_finish" version="2.26" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the permission was successfully acquired</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult given to the #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="get_allowed" c:identifier="g_permission_get_allowed" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value of the 'allowed' property</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_can_acquire" c:identifier="g_permission_get_can_acquire" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value of the 'can-acquire' property</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_can_release" c:identifier="g_permission_get_can_release" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value of the 'can-release' property</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </instance-parameter> + </parameters> + </method> + <method name="impl_update" c:identifier="g_permission_impl_update" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </instance-parameter> + <parameter name="allowed" transfer-ownership="none"> + <doc xml:space="preserve">the new value for the 'allowed' property</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="can_acquire" transfer-ownership="none"> + <doc xml:space="preserve">the new value for the 'can-acquire' property</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="can_release" transfer-ownership="none"> + <doc xml:space="preserve">the new value for the 'can-release' property</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="release" c:identifier="g_permission_release" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the permission was successfully released</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="release_async" c:identifier="g_permission_release_async" version="2.26"> + <doc xml:space="preserve">Attempts to release the permission represented by @permission. + +This is the first half of the asynchronous version of +g_permission_release().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">the #GAsyncReadyCallback to call when done</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="release_finish" c:identifier="g_permission_release_finish" version="2.26" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the permission was successfully released</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult given to the #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <property name="allowed" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the caller currently has permission to perform the action that +@permission represents the permission to perform.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="can-acquire" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if it is generally possible to acquire the permission by calling +g_permission_acquire().</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="can-release" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if it is generally possible to release the permission by calling +g_permission_release().</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="PermissionPrivate" c:type="GPermissionPrivate*"/> + </field> + </class> + <record name="PermissionClass" c:type="GPermissionClass" glib:is-gtype-struct-for="Permission"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="acquire"> + <callback name="acquire" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the permission was successfully acquired</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="acquire_async"> + <callback name="acquire_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">the #GAsyncReadyCallback to call when done</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="acquire_finish"> + <callback name="acquire_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the permission was successfully acquired</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult given to the #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="release"> + <callback name="release" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the permission was successfully released</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="release_async"> + <callback name="release_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">the #GAsyncReadyCallback to call when done</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the user data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="release_finish"> + <callback name="release_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the permission was successfully released</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="permission" transfer-ownership="none"> + <doc xml:space="preserve">a #GPermission instance</doc> + <type name="Permission" c:type="GPermission*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult given to the #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="reserved"> + <array zero-terminated="0" fixed-size="16"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <record name="PermissionPrivate" c:type="GPermissionPrivate" disguised="1"/> + <interface name="PollableInputStream" c:symbol-prefix="pollable_input_stream" c:type="GPollableInputStream" version="2.28" glib:type-name="GPollableInputStream" glib:get-type="g_pollable_input_stream_get_type" glib:type-struct="PollableInputStreamInterface"> + <doc xml:space="preserve">#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.</doc> + <prerequisite name="InputStream"/> + <virtual-method name="can_poll" invoker="can_poll" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @stream is pollable, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableInputStream.</doc> + <type name="PollableInputStream" c:type="GPollableInputStream*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="create_source" invoker="create_source" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSource</doc> + <type name="GLib.Source" c:type="GSource*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableInputStream.</doc> + <type name="PollableInputStream" c:type="GPollableInputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="is_readable" invoker="is_readable" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%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.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableInputStream.</doc> + <type name="PollableInputStream" c:type="GPollableInputStream*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="read_nonblocking" invoker="read_nonblocking" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes read, or -1 on error (including + %G_IO_ERROR_WOULD_BLOCK).</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableInputStream</doc> + <type name="PollableInputStream" c:type="GPollableInputStream*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a buffer to + read data into (which should be at least @count bytes long).</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes you want to read</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </virtual-method> + <method name="can_poll" c:identifier="g_pollable_input_stream_can_poll" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @stream is pollable, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableInputStream.</doc> + <type name="PollableInputStream" c:type="GPollableInputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="create_source" c:identifier="g_pollable_input_stream_create_source" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSource</doc> + <type name="GLib.Source" c:type="GSource*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableInputStream.</doc> + <type name="PollableInputStream" c:type="GPollableInputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="is_readable" c:identifier="g_pollable_input_stream_is_readable" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%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.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableInputStream.</doc> + <type name="PollableInputStream" c:type="GPollableInputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="read_nonblocking" c:identifier="g_pollable_input_stream_read_nonblocking" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes read, or -1 on error (including + %G_IO_ERROR_WOULD_BLOCK).</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableInputStream</doc> + <type name="PollableInputStream" c:type="GPollableInputStream*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">a buffer to + read data into (which should be at least @count bytes long).</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes you want to read</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + </interface> + <record name="PollableInputStreamInterface" c:type="GPollableInputStreamInterface" glib:is-gtype-struct-for="PollableInputStream" version="2.28"> + <doc xml:space="preserve">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.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="can_poll"> + <callback name="can_poll"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @stream is pollable, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableInputStream.</doc> + <type name="PollableInputStream" c:type="GPollableInputStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="is_readable"> + <callback name="is_readable"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%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.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableInputStream.</doc> + <type name="PollableInputStream" c:type="GPollableInputStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="create_source"> + <callback name="create_source"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSource</doc> + <type name="GLib.Source" c:type="GSource*"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableInputStream.</doc> + <type name="PollableInputStream" c:type="GPollableInputStream*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="read_nonblocking"> + <callback name="read_nonblocking" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes read, or -1 on error (including + %G_IO_ERROR_WOULD_BLOCK).</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableInputStream</doc> + <type name="PollableInputStream" c:type="GPollableInputStream*"/> + </parameter> + <parameter name="buffer" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a buffer to + read data into (which should be at least @count bytes long).</doc> + <array length="2" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes you want to read</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <interface name="PollableOutputStream" c:symbol-prefix="pollable_output_stream" c:type="GPollableOutputStream" version="2.28" glib:type-name="GPollableOutputStream" glib:get-type="g_pollable_output_stream_get_type" glib:type-struct="PollableOutputStreamInterface"> + <doc xml:space="preserve">#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.</doc> + <prerequisite name="OutputStream"/> + <virtual-method name="can_poll" invoker="can_poll" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @stream is pollable, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableOutputStream.</doc> + <type name="PollableOutputStream" c:type="GPollableOutputStream*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="create_source" invoker="create_source" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSource</doc> + <type name="GLib.Source" c:type="GSource*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableOutputStream.</doc> + <type name="PollableOutputStream" c:type="GPollableOutputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="is_writable" invoker="is_writable" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%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.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableOutputStream.</doc> + <type name="PollableOutputStream" c:type="GPollableOutputStream*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="write_nonblocking" invoker="write_nonblocking" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes written, or -1 on error (including + %G_IO_ERROR_WOULD_BLOCK).</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableOutputStream</doc> + <type name="PollableOutputStream" c:type="GPollableOutputStream*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a buffer to write + data from</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes you want to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="writev_nonblocking" invoker="writev_nonblocking" version="2.60" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%@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.</doc> + <type name="PollableReturn" c:type="GPollableReturn"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableOutputStream</doc> + <type name="PollableOutputStream" c:type="GPollableOutputStream*"/> + </instance-parameter> + <parameter name="vectors" transfer-ownership="none"> + <doc xml:space="preserve">the buffer containing the #GOutputVectors to write.</doc> + <array length="1" zero-terminated="0" c:type="const GOutputVector*"> + <type name="OutputVector" c:type="GOutputVector"/> + </array> + </parameter> + <parameter name="n_vectors" transfer-ownership="none"> + <doc xml:space="preserve">the number of vectors to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the number of bytes that were + written to the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </virtual-method> + <method name="can_poll" c:identifier="g_pollable_output_stream_can_poll" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @stream is pollable, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableOutputStream.</doc> + <type name="PollableOutputStream" c:type="GPollableOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="create_source" c:identifier="g_pollable_output_stream_create_source" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSource</doc> + <type name="GLib.Source" c:type="GSource*"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableOutputStream.</doc> + <type name="PollableOutputStream" c:type="GPollableOutputStream*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="is_writable" c:identifier="g_pollable_output_stream_is_writable" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%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.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableOutputStream.</doc> + <type name="PollableOutputStream" c:type="GPollableOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="write_nonblocking" c:identifier="g_pollable_output_stream_write_nonblocking" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes written, or -1 on error (including + %G_IO_ERROR_WOULD_BLOCK).</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableOutputStream</doc> + <type name="PollableOutputStream" c:type="GPollableOutputStream*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">a buffer to write + data from</doc> + <array length="1" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes you want to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="writev_nonblocking" c:identifier="g_pollable_output_stream_writev_nonblocking" version="2.60" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%@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.</doc> + <type name="PollableReturn" c:type="GPollableReturn"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableOutputStream</doc> + <type name="PollableOutputStream" c:type="GPollableOutputStream*"/> + </instance-parameter> + <parameter name="vectors" transfer-ownership="none"> + <doc xml:space="preserve">the buffer containing the #GOutputVectors to write.</doc> + <array length="1" zero-terminated="0" c:type="const GOutputVector*"> + <type name="OutputVector" c:type="GOutputVector"/> + </array> + </parameter> + <parameter name="n_vectors" transfer-ownership="none"> + <doc xml:space="preserve">the number of vectors to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the number of bytes that were + written to the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + </interface> + <record name="PollableOutputStreamInterface" c:type="GPollableOutputStreamInterface" glib:is-gtype-struct-for="PollableOutputStream" version="2.28"> + <doc xml:space="preserve">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.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="can_poll"> + <callback name="can_poll"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @stream is pollable, %FALSE if not.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableOutputStream.</doc> + <type name="PollableOutputStream" c:type="GPollableOutputStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="is_writable"> + <callback name="is_writable"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%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.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableOutputStream.</doc> + <type name="PollableOutputStream" c:type="GPollableOutputStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="create_source"> + <callback name="create_source"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSource</doc> + <type name="GLib.Source" c:type="GSource*"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableOutputStream.</doc> + <type name="PollableOutputStream" c:type="GPollableOutputStream*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="write_nonblocking"> + <callback name="write_nonblocking" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes written, or -1 on error (including + %G_IO_ERROR_WOULD_BLOCK).</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableOutputStream</doc> + <type name="PollableOutputStream" c:type="GPollableOutputStream*"/> + </parameter> + <parameter name="buffer" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a buffer to write + data from</doc> + <array length="2" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes you want to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </callback> + </field> + <field name="writev_nonblocking"> + <callback name="writev_nonblocking" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%@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.</doc> + <type name="PollableReturn" c:type="GPollableReturn"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GPollableOutputStream</doc> + <type name="PollableOutputStream" c:type="GPollableOutputStream*"/> + </parameter> + <parameter name="vectors" transfer-ownership="none"> + <doc xml:space="preserve">the buffer containing the #GOutputVectors to write.</doc> + <array length="2" zero-terminated="0" c:type="const GOutputVector*"> + <type name="OutputVector" c:type="GOutputVector"/> + </array> + </parameter> + <parameter name="n_vectors" transfer-ownership="none"> + <doc xml:space="preserve">the number of vectors to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the number of bytes that were + written to the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <enumeration name="PollableReturn" version="2.60" glib:type-name="GPollableReturn" glib:get-type="g_pollable_return_get_type" c:type="GPollableReturn"> + <doc xml:space="preserve">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.</doc> + <member name="failed" value="0" c:identifier="G_POLLABLE_RETURN_FAILED" glib:nick="failed"> + <doc xml:space="preserve">Generic error condition for when an operation fails.</doc> + </member> + <member name="ok" value="1" c:identifier="G_POLLABLE_RETURN_OK" glib:nick="ok"> + <doc xml:space="preserve">The operation was successfully finished.</doc> + </member> + <member name="would_block" value="-27" c:identifier="G_POLLABLE_RETURN_WOULD_BLOCK" glib:nick="would-block"> + <doc xml:space="preserve">The operation would block.</doc> + </member> + </enumeration> + <callback name="PollableSourceFunc" c:type="GPollableSourceFunc" version="2.28"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">it should return %FALSE if the source should be removed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="pollable_stream" transfer-ownership="none"> + <doc xml:space="preserve">the #GPollableInputStream or #GPollableOutputStream</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="1"> + <doc xml:space="preserve">data passed in by the user.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <class name="PropertyAction" c:symbol-prefix="property_action" c:type="GPropertyAction" version="2.38" parent="GObject.Object" glib:type-name="GPropertyAction" glib:get-type="g_property_action_get_type"> + <doc xml:space="preserve">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().</doc> + <implements name="Action"/> + <constructor name="new" c:identifier="g_property_action_new" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GPropertyAction</doc> + <type name="PropertyAction" c:type="GPropertyAction*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to create</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">the object that has the property + to wrap</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + <parameter name="property_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the property</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <property name="enabled" version="2.38" transfer-ownership="none"> + <doc xml:space="preserve">If @action is currently enabled. + +If the action is disabled then calls to g_action_activate() and +g_action_change_state() have no effect.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="invert-boolean" version="2.46" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">If %TRUE, the state of the action will be the negation of the +property value, provided the property is boolean.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="name" version="2.38" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The name of the action. This is mostly meaningful for identifying +the action once it has been added to a #GActionMap.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="object" version="2.38" readable="0" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The object to wrap a property on. + +The object must be a non-%NULL #GObject with properties.</doc> + <type name="GObject.Object"/> + </property> + <property name="parameter-type" version="2.38" transfer-ownership="none"> + <doc xml:space="preserve">The type of the parameter that must be given when activating the +action.</doc> + <type name="GLib.VariantType"/> + </property> + <property name="property-name" version="2.38" readable="0" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">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).</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="state" version="2.38" transfer-ownership="none"> + <doc xml:space="preserve">The state of the action, or %NULL if the action is stateless.</doc> + <type name="GLib.Variant"/> + </property> + <property name="state-type" version="2.38" transfer-ownership="none"> + <doc xml:space="preserve">The #GVariantType of the state that the action has, or %NULL if the +action is stateless.</doc> + <type name="GLib.VariantType"/> + </property> + </class> + <interface name="Proxy" c:symbol-prefix="proxy" c:type="GProxy" version="2.26" glib:type-name="GProxy" glib:get-type="g_proxy_get_type" glib:type-struct="ProxyInterface"> + <doc xml:space="preserve">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().</doc> + <function name="get_default_for_protocol" c:identifier="g_proxy_get_default_for_protocol" version="2.26"> + <doc xml:space="preserve">Find the `gio-proxy` extension point for a proxy implementation that supports +the specified protocol.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">return a #GProxy or NULL if protocol + is not supported.</doc> + <type name="Proxy" c:type="GProxy*"/> + </return-value> + <parameters> + <parameter name="protocol" transfer-ownership="none"> + <doc xml:space="preserve">the proxy protocol name (e.g. http, socks, etc)</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <virtual-method name="connect" invoker="connect" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIOStream that will replace @connection. This might + be the same as @connection, in which case a reference + will be added.</doc> + <type name="IOStream" c:type="GIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxy</doc> + <type name="Proxy" c:type="GProxy*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="proxy_address" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyAddress</doc> + <type name="ProxyAddress" c:type="GProxyAddress*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="connect_async" invoker="connect_async" version="2.26"> + <doc xml:space="preserve">Asynchronous version of g_proxy_connect().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxy</doc> + <type name="Proxy" c:type="GProxy*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="proxy_address" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyAddress</doc> + <type name="ProxyAddress" c:type="GProxyAddress*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">callback data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="connect_finish" invoker="connect_finish" version="2.26" throws="1"> + <doc xml:space="preserve">See g_proxy_connect().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIOStream.</doc> + <type name="IOStream" c:type="GIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxy</doc> + <type name="Proxy" c:type="GProxy*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="supports_hostname" invoker="supports_hostname" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if hostname resolution is supported.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxy</doc> + <type name="Proxy" c:type="GProxy*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="connect" c:identifier="g_proxy_connect" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIOStream that will replace @connection. This might + be the same as @connection, in which case a reference + will be added.</doc> + <type name="IOStream" c:type="GIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxy</doc> + <type name="Proxy" c:type="GProxy*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="proxy_address" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyAddress</doc> + <type name="ProxyAddress" c:type="GProxyAddress*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="connect_async" c:identifier="g_proxy_connect_async" version="2.26"> + <doc xml:space="preserve">Asynchronous version of g_proxy_connect().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxy</doc> + <type name="Proxy" c:type="GProxy*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="proxy_address" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyAddress</doc> + <type name="ProxyAddress" c:type="GProxyAddress*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">callback data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="connect_finish" c:identifier="g_proxy_connect_finish" version="2.26" throws="1"> + <doc xml:space="preserve">See g_proxy_connect().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIOStream.</doc> + <type name="IOStream" c:type="GIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxy</doc> + <type name="Proxy" c:type="GProxy*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="supports_hostname" c:identifier="g_proxy_supports_hostname" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if hostname resolution is supported.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxy</doc> + <type name="Proxy" c:type="GProxy*"/> + </instance-parameter> + </parameters> + </method> + </interface> + <class name="ProxyAddress" c:symbol-prefix="proxy_address" c:type="GProxyAddress" version="2.26" parent="InetSocketAddress" glib:type-name="GProxyAddress" glib:get-type="g_proxy_address_get_type" glib:type-struct="ProxyAddressClass"> + <doc xml:space="preserve">Support for proxied #GInetSocketAddress.</doc> + <implements name="SocketConnectable"/> + <constructor name="new" c:identifier="g_proxy_address_new" version="2.26"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GProxyAddress</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <parameter name="inetaddr" transfer-ownership="none"> + <doc xml:space="preserve">The proxy server #GInetAddress.</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + <parameter name="port" transfer-ownership="none"> + <doc xml:space="preserve">The proxy server port.</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + <parameter name="protocol" transfer-ownership="none"> + <doc xml:space="preserve">The proxy protocol to support, in lower case (e.g. socks, http).</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="dest_hostname" transfer-ownership="none"> + <doc xml:space="preserve">The destination hostname the proxy should tunnel to.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="dest_port" transfer-ownership="none"> + <doc xml:space="preserve">The destination port to tunnel to.</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + <parameter name="username" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The username to authenticate to the proxy server + (or %NULL).</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="password" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">The password to authenticate to the proxy server + (or %NULL).</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <method name="get_destination_hostname" c:identifier="g_proxy_address_get_destination_hostname" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the @proxy's destination hostname</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyAddress</doc> + <type name="ProxyAddress" c:type="GProxyAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_destination_port" c:identifier="g_proxy_address_get_destination_port" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the @proxy's destination port</doc> + <type name="guint16" c:type="guint16"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyAddress</doc> + <type name="ProxyAddress" c:type="GProxyAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_destination_protocol" c:identifier="g_proxy_address_get_destination_protocol" version="2.34"> + <doc xml:space="preserve">Gets the protocol that is being spoken to the destination +server; eg, "http" or "ftp".</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the @proxy's destination protocol</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyAddress</doc> + <type name="ProxyAddress" c:type="GProxyAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_password" c:identifier="g_proxy_address_get_password" version="2.26"> + <doc xml:space="preserve">Gets @proxy's password.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the @proxy's password</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyAddress</doc> + <type name="ProxyAddress" c:type="GProxyAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_protocol" c:identifier="g_proxy_address_get_protocol" version="2.26"> + <doc xml:space="preserve">Gets @proxy's protocol. eg, "socks" or "http"</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the @proxy's protocol</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyAddress</doc> + <type name="ProxyAddress" c:type="GProxyAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_uri" c:identifier="g_proxy_address_get_uri" version="2.34"> + <doc xml:space="preserve">Gets the proxy URI that @proxy was constructed from.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the @proxy's URI, or %NULL if unknown</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyAddress</doc> + <type name="ProxyAddress" c:type="GProxyAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_username" c:identifier="g_proxy_address_get_username" version="2.26"> + <doc xml:space="preserve">Gets @proxy's username.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the @proxy's username</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyAddress</doc> + <type name="ProxyAddress" c:type="GProxyAddress*"/> + </instance-parameter> + </parameters> + </method> + <property name="destination-hostname" writable="1" construct-only="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="destination-port" writable="1" construct-only="1" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </property> + <property name="destination-protocol" version="2.34" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The protocol being spoke to the destination host, or %NULL if +the #GProxyAddress doesn't know.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="password" writable="1" construct-only="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="protocol" writable="1" construct-only="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="uri" version="2.34" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The URI string that the proxy was constructed from (or %NULL +if the creator didn't specify this).</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="username" writable="1" construct-only="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <field name="parent_instance"> + <type name="InetSocketAddress" c:type="GInetSocketAddress"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="ProxyAddressPrivate" c:type="GProxyAddressPrivate*"/> + </field> + </class> + <record name="ProxyAddressClass" c:type="GProxyAddressClass" glib:is-gtype-struct-for="ProxyAddress" version="2.26"> + <doc xml:space="preserve">Class structure for #GProxyAddress.</doc> + <field name="parent_class"> + <type name="InetSocketAddressClass" c:type="GInetSocketAddressClass"/> + </field> + </record> + <class name="ProxyAddressEnumerator" c:symbol-prefix="proxy_address_enumerator" c:type="GProxyAddressEnumerator" parent="SocketAddressEnumerator" glib:type-name="GProxyAddressEnumerator" glib:get-type="g_proxy_address_enumerator_get_type" glib:type-struct="ProxyAddressEnumeratorClass"> + <doc xml:space="preserve">#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.</doc> + <property name="connectable" writable="1" construct-only="1" transfer-ownership="none"> + <type name="SocketConnectable"/> + </property> + <property name="default-port" version="2.38" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The default port to use if #GProxyAddressEnumerator:uri does not +specify one.</doc> + <type name="guint" c:type="guint"/> + </property> + <property name="proxy-resolver" version="2.36" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">The proxy resolver to use.</doc> + <type name="ProxyResolver"/> + </property> + <property name="uri" writable="1" construct-only="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <field name="parent_instance" readable="0" private="1"> + <type name="SocketAddressEnumerator" c:type="GSocketAddressEnumerator"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="ProxyAddressEnumeratorPrivate" c:type="GProxyAddressEnumeratorPrivate*"/> + </field> + </class> + <record name="ProxyAddressEnumeratorClass" c:type="GProxyAddressEnumeratorClass" glib:is-gtype-struct-for="ProxyAddressEnumerator"> + <doc xml:space="preserve">Class structure for #GProxyAddressEnumerator.</doc> + <field name="parent_class" readable="0" private="1"> + <type name="SocketAddressEnumeratorClass" c:type="GSocketAddressEnumeratorClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved6" introspectable="0"> + <callback name="_g_reserved6"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved7" introspectable="0"> + <callback name="_g_reserved7"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="ProxyAddressEnumeratorPrivate" c:type="GProxyAddressEnumeratorPrivate" disguised="1"/> + <record name="ProxyAddressPrivate" c:type="GProxyAddressPrivate" disguised="1"/> + <record name="ProxyInterface" c:type="GProxyInterface" glib:is-gtype-struct-for="Proxy" version="2.26"> + <doc xml:space="preserve">Provides an interface for handling proxy connection and payload.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="connect"> + <callback name="connect" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIOStream that will replace @connection. This might + be the same as @connection, in which case a reference + will be added.</doc> + <type name="IOStream" c:type="GIOStream*"/> + </return-value> + <parameters> + <parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxy</doc> + <type name="Proxy" c:type="GProxy*"/> + </parameter> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="proxy_address" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyAddress</doc> + <type name="ProxyAddress" c:type="GProxyAddress*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="connect_async"> + <callback name="connect_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxy</doc> + <type name="Proxy" c:type="GProxy*"/> + </parameter> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="proxy_address" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyAddress</doc> + <type name="ProxyAddress" c:type="GProxyAddress*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">callback data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="connect_finish"> + <callback name="connect_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIOStream.</doc> + <type name="IOStream" c:type="GIOStream*"/> + </return-value> + <parameters> + <parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxy</doc> + <type name="Proxy" c:type="GProxy*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="supports_hostname"> + <callback name="supports_hostname"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if hostname resolution is supported.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxy</doc> + <type name="Proxy" c:type="GProxy*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <interface name="ProxyResolver" c:symbol-prefix="proxy_resolver" c:type="GProxyResolver" version="2.26" glib:type-name="GProxyResolver" glib:get-type="g_proxy_resolver_get_type" glib:type-struct="ProxyResolverInterface"> + <doc xml:space="preserve">#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.</doc> + <function name="get_default" c:identifier="g_proxy_resolver_get_default" version="2.26"> + <doc xml:space="preserve">Gets the default #GProxyResolver for the system.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the default #GProxyResolver, which + will be a dummy object if no proxy resolver is available</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </return-value> + </function> + <virtual-method name="is_supported" invoker="is_supported" version="2.26"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @resolver is supported.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyResolver</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup" invoker="lookup" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A + NULL-terminated array of proxy URIs. Must be freed + with g_strfreev().</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyResolver</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a URI representing the destination to connect to</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_async" invoker="lookup_async" version="2.26"> + <doc xml:space="preserve">Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more +details.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyResolver</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a URI representing the destination to connect to</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call after resolution completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_finish" invoker="lookup_finish" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A + NULL-terminated array of proxy URIs. Must be freed + with g_strfreev().</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyResolver</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <method name="is_supported" c:identifier="g_proxy_resolver_is_supported" version="2.26"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @resolver is supported.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyResolver</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </instance-parameter> + </parameters> + </method> + <method name="lookup" c:identifier="g_proxy_resolver_lookup" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A + NULL-terminated array of proxy URIs. Must be freed + with g_strfreev().</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyResolver</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a URI representing the destination to connect to</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="lookup_async" c:identifier="g_proxy_resolver_lookup_async" version="2.26"> + <doc xml:space="preserve">Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more +details.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyResolver</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a URI representing the destination to connect to</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call after resolution completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="lookup_finish" c:identifier="g_proxy_resolver_lookup_finish" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A + NULL-terminated array of proxy URIs. Must be freed + with g_strfreev().</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyResolver</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + </interface> + <record name="ProxyResolverInterface" c:type="GProxyResolverInterface" glib:is-gtype-struct-for="ProxyResolver"> + <doc xml:space="preserve">The virtual function table for #GProxyResolver.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="is_supported"> + <callback name="is_supported"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @resolver is supported.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyResolver</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup"> + <callback name="lookup" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A + NULL-terminated array of proxy URIs. Must be freed + with g_strfreev().</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyResolver</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a URI representing the destination to connect to</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_async"> + <callback name="lookup_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyResolver</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a URI representing the destination to connect to</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call after resolution completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_finish"> + <callback name="lookup_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A + NULL-terminated array of proxy URIs. Must be freed + with g_strfreev().</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GProxyResolver</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <function-macro name="REMOTE_ACTION_GROUP" c:identifier="G_REMOTE_ACTION_GROUP" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="REMOTE_ACTION_GROUP_GET_IFACE" c:identifier="G_REMOTE_ACTION_GROUP_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="RESOLVER" c:identifier="G_RESOLVER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="RESOLVER_CLASS" c:identifier="G_RESOLVER_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="RESOLVER_GET_CLASS" c:identifier="G_RESOLVER_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <callback name="ReallocFunc" c:type="GReallocFunc"> + <doc xml:space="preserve">Changes the size of the memory block pointed to by @data to +@size bytes. + +The function should have the same semantics as realloc().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a pointer to the reallocated memory</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">memory block to reallocate</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">size to reallocate @data to</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </callback> + <interface name="RemoteActionGroup" c:symbol-prefix="remote_action_group" c:type="GRemoteActionGroup" version="2.32" glib:type-name="GRemoteActionGroup" glib:get-type="g_remote_action_group_get_type" glib:type-struct="RemoteActionGroupInterface"> + <doc xml:space="preserve">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.</doc> + <prerequisite name="ActionGroup"/> + <virtual-method name="activate_action_full" invoker="activate_action_full" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="remote" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusActionGroup</doc> + <type name="RemoteActionGroup" c:type="GRemoteActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to activate</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameter" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the optional parameter to the activation</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="platform_data" transfer-ownership="none"> + <doc xml:space="preserve">the platform data to send</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="change_action_state_full" invoker="change_action_state_full" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="remote" transfer-ownership="none"> + <doc xml:space="preserve">a #GRemoteActionGroup</doc> + <type name="RemoteActionGroup" c:type="GRemoteActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to change the state of</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the new requested value for the state</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="platform_data" transfer-ownership="none"> + <doc xml:space="preserve">the platform data to send</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <method name="activate_action_full" c:identifier="g_remote_action_group_activate_action_full" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="remote" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusActionGroup</doc> + <type name="RemoteActionGroup" c:type="GRemoteActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to activate</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameter" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the optional parameter to the activation</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="platform_data" transfer-ownership="none"> + <doc xml:space="preserve">the platform data to send</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="change_action_state_full" c:identifier="g_remote_action_group_change_action_state_full" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="remote" transfer-ownership="none"> + <doc xml:space="preserve">a #GRemoteActionGroup</doc> + <type name="RemoteActionGroup" c:type="GRemoteActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to change the state of</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the new requested value for the state</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="platform_data" transfer-ownership="none"> + <doc xml:space="preserve">the platform data to send</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + </interface> + <record name="RemoteActionGroupInterface" c:type="GRemoteActionGroupInterface" glib:is-gtype-struct-for="RemoteActionGroup" version="2.32"> + <doc xml:space="preserve">The virtual function table for #GRemoteActionGroup.</doc> + <field name="g_iface"> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="activate_action_full"> + <callback name="activate_action_full"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="remote" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusActionGroup</doc> + <type name="RemoteActionGroup" c:type="GRemoteActionGroup*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to activate</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameter" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the optional parameter to the activation</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="platform_data" transfer-ownership="none"> + <doc xml:space="preserve">the platform data to send</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="change_action_state_full"> + <callback name="change_action_state_full"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="remote" transfer-ownership="none"> + <doc xml:space="preserve">a #GRemoteActionGroup</doc> + <type name="RemoteActionGroup" c:type="GRemoteActionGroup*"/> + </parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action to change the state of</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the new requested value for the state</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="platform_data" transfer-ownership="none"> + <doc xml:space="preserve">the platform data to send</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="Resolver" c:symbol-prefix="resolver" c:type="GResolver" parent="GObject.Object" abstract="1" glib:type-name="GResolver" glib:get-type="g_resolver_get_type" glib:type-struct="ResolverClass"> + <doc xml:space="preserve">#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.</doc> + <function name="free_addresses" c:identifier="g_resolver_free_addresses" version="2.22" introspectable="0"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="addresses" transfer-ownership="none"> + <doc xml:space="preserve">a #GList of #GInetAddress</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="free_targets" c:identifier="g_resolver_free_targets" version="2.22" introspectable="0"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="targets" transfer-ownership="none"> + <doc xml:space="preserve">a #GList of #GSrvTarget</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="get_default" c:identifier="g_resolver_get_default" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the default #GResolver.</doc> + <type name="Resolver" c:type="GResolver*"/> + </return-value> + </function> + <virtual-method name="lookup_by_address" invoker="lookup_by_address" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a hostname (either ASCII-only, or in ASCII-encoded + form), or %NULL on error.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">the address to reverse-resolve</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_by_address_async" invoker="lookup_by_address_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">the address to reverse-resolve</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call after resolution completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_by_address_finish" invoker="lookup_by_address_finish" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a hostname (either ASCII-only, or in ASCII-encoded +form), or %NULL on error.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_by_name" invoker="lookup_by_name" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.)</doc> + <type name="GLib.List" c:type="GList*"> + <type name="InetAddress"/> + </type> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">the hostname to look up</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_by_name_async" invoker="lookup_by_name_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">the hostname to look up the address of</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call after resolution completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_by_name_finish" invoker="lookup_by_name_finish" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GList +of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() +for more details.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="InetAddress"/> + </type> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_by_name_with_flags" invoker="lookup_by_name_with_flags" version="2.60" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.)</doc> + <type name="GLib.List" c:type="GList*"> + <type name="InetAddress"/> + </type> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">the hostname to look up</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">extra #GResolverNameLookupFlags for the lookup</doc> + <type name="ResolverNameLookupFlags" c:type="GResolverNameLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_by_name_with_flags_async" invoker="lookup_by_name_with_flags_async" version="2.60"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">the hostname to look up the address of</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">extra #GResolverNameLookupFlags for the lookup</doc> + <type name="ResolverNameLookupFlags" c:type="GResolverNameLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call after resolution completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_by_name_with_flags_finish" invoker="lookup_by_name_with_flags_finish" version="2.60" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GList +of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() +for more details.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="InetAddress"/> + </type> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_records" invoker="lookup_records" version="2.34" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.)</doc> + <type name="GLib.List" c:type="GList*"> + <type name="GLib.Variant"/> + </type> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="rrname" transfer-ownership="none"> + <doc xml:space="preserve">the DNS name to look up the record for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="record_type" transfer-ownership="none"> + <doc xml:space="preserve">the type of DNS record to look up</doc> + <type name="ResolverRecordType" c:type="GResolverRecordType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_records_async" invoker="lookup_records_async" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="rrname" transfer-ownership="none"> + <doc xml:space="preserve">the DNS name to look up the record for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="record_type" transfer-ownership="none"> + <doc xml:space="preserve">the type of DNS record to look up</doc> + <type name="ResolverRecordType" c:type="GResolverRecordType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call after resolution completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_records_finish" invoker="lookup_records_finish" version="2.34" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.)</doc> + <type name="GLib.List" c:type="GList*"> + <type name="GLib.Variant"/> + </type> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_service" introspectable="0" throws="1"> + <return-value> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="rrname" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_service_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="rrname" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_service_finish" invoker="lookup_service_finish" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a non-empty #GList of +#GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more +details.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="SrvTarget"/> + </type> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="reload"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="lookup_by_address" c:identifier="g_resolver_lookup_by_address" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a hostname (either ASCII-only, or in ASCII-encoded + form), or %NULL on error.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">the address to reverse-resolve</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="lookup_by_address_async" c:identifier="g_resolver_lookup_by_address_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">the address to reverse-resolve</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call after resolution completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="lookup_by_address_finish" c:identifier="g_resolver_lookup_by_address_finish" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a hostname (either ASCII-only, or in ASCII-encoded +form), or %NULL on error.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="lookup_by_name" c:identifier="g_resolver_lookup_by_name" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.)</doc> + <type name="GLib.List" c:type="GList*"> + <type name="InetAddress"/> + </type> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">the hostname to look up</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="lookup_by_name_async" c:identifier="g_resolver_lookup_by_name_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">the hostname to look up the address of</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call after resolution completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="lookup_by_name_finish" c:identifier="g_resolver_lookup_by_name_finish" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GList +of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() +for more details.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="InetAddress"/> + </type> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="lookup_by_name_with_flags" c:identifier="g_resolver_lookup_by_name_with_flags" version="2.60" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.)</doc> + <type name="GLib.List" c:type="GList*"> + <type name="InetAddress"/> + </type> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">the hostname to look up</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">extra #GResolverNameLookupFlags for the lookup</doc> + <type name="ResolverNameLookupFlags" c:type="GResolverNameLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="lookup_by_name_with_flags_async" c:identifier="g_resolver_lookup_by_name_with_flags_async" version="2.60"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">the hostname to look up the address of</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">extra #GResolverNameLookupFlags for the lookup</doc> + <type name="ResolverNameLookupFlags" c:type="GResolverNameLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call after resolution completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="lookup_by_name_with_flags_finish" c:identifier="g_resolver_lookup_by_name_with_flags_finish" version="2.60" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GList +of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() +for more details.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="InetAddress"/> + </type> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="lookup_records" c:identifier="g_resolver_lookup_records" version="2.34" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.)</doc> + <type name="GLib.List" c:type="GList*"> + <type name="GLib.Variant"/> + </type> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="rrname" transfer-ownership="none"> + <doc xml:space="preserve">the DNS name to look up the record for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="record_type" transfer-ownership="none"> + <doc xml:space="preserve">the type of DNS record to look up</doc> + <type name="ResolverRecordType" c:type="GResolverRecordType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="lookup_records_async" c:identifier="g_resolver_lookup_records_async" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="rrname" transfer-ownership="none"> + <doc xml:space="preserve">the DNS name to look up the record for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="record_type" transfer-ownership="none"> + <doc xml:space="preserve">the type of DNS record to look up</doc> + <type name="ResolverRecordType" c:type="GResolverRecordType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call after resolution completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="lookup_records_finish" c:identifier="g_resolver_lookup_records_finish" version="2.34" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.)</doc> + <type name="GLib.List" c:type="GList*"> + <type name="GLib.Variant"/> + </type> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="lookup_service" c:identifier="g_resolver_lookup_service" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.)</doc> + <type name="GLib.List" c:type="GList*"> + <type name="SrvTarget"/> + </type> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="service" transfer-ownership="none"> + <doc xml:space="preserve">the service type to look up (eg, "ldap")</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="protocol" transfer-ownership="none"> + <doc xml:space="preserve">the networking protocol to use for @service (eg, "tcp")</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">the DNS domain to look up the service in</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="lookup_service_async" c:identifier="g_resolver_lookup_service_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="service" transfer-ownership="none"> + <doc xml:space="preserve">the service type to look up (eg, "ldap")</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="protocol" transfer-ownership="none"> + <doc xml:space="preserve">the networking protocol to use for @service (eg, "tcp")</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">the DNS domain to look up the service in</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call after resolution completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="lookup_service_finish" c:identifier="g_resolver_lookup_service_finish" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a non-empty #GList of +#GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more +details.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="SrvTarget"/> + </type> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="set_default" c:identifier="g_resolver_set_default" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">the new default #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </instance-parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv"> + <type name="ResolverPrivate" c:type="GResolverPrivate*"/> + </field> + <glib:signal name="reload" when="last"> + <doc xml:space="preserve">Emitted when the resolver notices that the system resolver +configuration has changed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + </class> + <record name="ResolverClass" c:type="GResolverClass" glib:is-gtype-struct-for="Resolver"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="reload"> + <callback name="reload"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <type name="Resolver" c:type="GResolver*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_by_name"> + <callback name="lookup_by_name" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.)</doc> + <type name="GLib.List" c:type="GList*"> + <type name="InetAddress"/> + </type> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </parameter> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">the hostname to look up</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_by_name_async"> + <callback name="lookup_by_name_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </parameter> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">the hostname to look up the address of</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call after resolution completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_by_name_finish"> + <callback name="lookup_by_name_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GList +of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() +for more details.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="InetAddress"/> + </type> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_by_address"> + <callback name="lookup_by_address" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a hostname (either ASCII-only, or in ASCII-encoded + form), or %NULL on error.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </parameter> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">the address to reverse-resolve</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_by_address_async"> + <callback name="lookup_by_address_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </parameter> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">the address to reverse-resolve</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call after resolution completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_by_address_finish"> + <callback name="lookup_by_address_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a hostname (either ASCII-only, or in ASCII-encoded +form), or %NULL on error.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_service" introspectable="0"> + <callback name="lookup_service" introspectable="0" throws="1"> + <return-value> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <type name="Resolver" c:type="GResolver*"/> + </parameter> + <parameter name="rrname" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_service_async"> + <callback name="lookup_service_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <type name="Resolver" c:type="GResolver*"/> + </parameter> + <parameter name="rrname" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_service_finish"> + <callback name="lookup_service_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a non-empty #GList of +#GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more +details.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="SrvTarget"/> + </type> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_records"> + <callback name="lookup_records" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.)</doc> + <type name="GLib.List" c:type="GList*"> + <type name="GLib.Variant"/> + </type> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </parameter> + <parameter name="rrname" transfer-ownership="none"> + <doc xml:space="preserve">the DNS name to look up the record for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="record_type" transfer-ownership="none"> + <doc xml:space="preserve">the type of DNS record to look up</doc> + <type name="ResolverRecordType" c:type="GResolverRecordType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_records_async"> + <callback name="lookup_records_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </parameter> + <parameter name="rrname" transfer-ownership="none"> + <doc xml:space="preserve">the DNS name to look up the record for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="record_type" transfer-ownership="none"> + <doc xml:space="preserve">the type of DNS record to look up</doc> + <type name="ResolverRecordType" c:type="GResolverRecordType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call after resolution completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_records_finish"> + <callback name="lookup_records_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.)</doc> + <type name="GLib.List" c:type="GList*"> + <type name="GLib.Variant"/> + </type> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_by_name_with_flags_async"> + <callback name="lookup_by_name_with_flags_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </parameter> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">the hostname to look up the address of</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">extra #GResolverNameLookupFlags for the lookup</doc> + <type name="ResolverNameLookupFlags" c:type="GResolverNameLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call after resolution completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_by_name_with_flags_finish"> + <callback name="lookup_by_name_with_flags_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GList +of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() +for more details.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="InetAddress"/> + </type> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_by_name_with_flags"> + <callback name="lookup_by_name_with_flags" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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.)</doc> + <type name="GLib.List" c:type="GList*"> + <type name="InetAddress"/> + </type> + </return-value> + <parameters> + <parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GResolver</doc> + <type name="Resolver" c:type="GResolver*"/> + </parameter> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">the hostname to look up</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">extra #GResolverNameLookupFlags for the lookup</doc> + <type name="ResolverNameLookupFlags" c:type="GResolverNameLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <enumeration name="ResolverError" version="2.22" glib:type-name="GResolverError" glib:get-type="g_resolver_error_get_type" c:type="GResolverError" glib:error-domain="g-resolver-error-quark"> + <doc xml:space="preserve">An error code used with %G_RESOLVER_ERROR in a #GError returned +from a #GResolver routine.</doc> + <member name="not_found" value="0" c:identifier="G_RESOLVER_ERROR_NOT_FOUND" glib:nick="not-found"> + <doc xml:space="preserve">the requested name/address/service was not + found</doc> + </member> + <member name="temporary_failure" value="1" c:identifier="G_RESOLVER_ERROR_TEMPORARY_FAILURE" glib:nick="temporary-failure"> + <doc xml:space="preserve">the requested information could not + be looked up due to a network error or similar problem</doc> + </member> + <member name="internal" value="2" c:identifier="G_RESOLVER_ERROR_INTERNAL" glib:nick="internal"> + <doc xml:space="preserve">unknown error</doc> + </member> + <function name="quark" c:identifier="g_resolver_error_quark" version="2.22"> + <doc xml:space="preserve">Gets the #GResolver Error Quark.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </return-value> + </function> + </enumeration> + <bitfield name="ResolverNameLookupFlags" version="2.60" glib:type-name="GResolverNameLookupFlags" glib:get-type="g_resolver_name_lookup_flags_get_type" c:type="GResolverNameLookupFlags"> + <doc xml:space="preserve">Flags to modify lookup behavior.</doc> + <member name="default" value="0" c:identifier="G_RESOLVER_NAME_LOOKUP_FLAGS_DEFAULT" glib:nick="default"> + <doc xml:space="preserve">default behavior (same as g_resolver_lookup_by_name())</doc> + </member> + <member name="ipv4_only" value="1" c:identifier="G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY" glib:nick="ipv4-only"> + <doc xml:space="preserve">only resolve ipv4 addresses</doc> + </member> + <member name="ipv6_only" value="2" c:identifier="G_RESOLVER_NAME_LOOKUP_FLAGS_IPV6_ONLY" glib:nick="ipv6-only"> + <doc xml:space="preserve">only resolve ipv6 addresses</doc> + </member> + </bitfield> + <record name="ResolverPrivate" c:type="GResolverPrivate" disguised="1"/> + <enumeration name="ResolverRecordType" version="2.34" glib:type-name="GResolverRecordType" glib:get-type="g_resolver_record_type_get_type" c:type="GResolverRecordType"> + <doc xml:space="preserve">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.</doc> + <member name="srv" value="1" c:identifier="G_RESOLVER_RECORD_SRV" glib:nick="srv"> + <doc xml:space="preserve">look up DNS SRV records for a domain</doc> + </member> + <member name="mx" value="2" c:identifier="G_RESOLVER_RECORD_MX" glib:nick="mx"> + <doc xml:space="preserve">look up DNS MX records for a domain</doc> + </member> + <member name="txt" value="3" c:identifier="G_RESOLVER_RECORD_TXT" glib:nick="txt"> + <doc xml:space="preserve">look up DNS TXT records for a name</doc> + </member> + <member name="soa" value="4" c:identifier="G_RESOLVER_RECORD_SOA" glib:nick="soa"> + <doc xml:space="preserve">look up DNS SOA records for a zone</doc> + </member> + <member name="ns" value="5" c:identifier="G_RESOLVER_RECORD_NS" glib:nick="ns"> + <doc xml:space="preserve">look up DNS NS records for a domain</doc> + </member> + </enumeration> + <record name="Resource" c:type="GResource" version="2.32" glib:type-name="GResource" glib:get-type="g_resource_get_type" c:symbol-prefix="resource"> + <doc xml:space="preserve">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` (deprecated since gdk-pixbuf 2.32) 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. +`to-pixdata` has been deprecated since gdk-pixbuf 2.32, as #GResource +supports embedding modern image formats just as well. Instead of using it, +embed a PNG or SVG file in your #GResource. + +`json-stripblanks` which will use the `json-glib-format` command to strip +ignorable whitespace from the JSON file. For this to work, the +`JSON_GLIB_FORMAT` environment variable must be set to the full path to the +`json-glib-format` executable, or it must be in the `PATH`; +otherwise the preprocessing step is skipped. In addition, at least version +1.6 of `json-glib-format` is required. + +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. It is ignored when running in a setuid process. + +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.</doc> + <constructor name="new_from_data" c:identifier="g_resource_new_from_data" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GResource, or %NULL on error</doc> + <type name="Resource" c:type="GResource*"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">A #GBytes</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + </parameters> + </constructor> + <method name="_register" c:identifier="g_resources_register" moved-to="resources_register" version="2.32"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resource" transfer-ownership="none"> + <doc xml:space="preserve">A #GResource</doc> + <type name="Resource" c:type="GResource*"/> + </instance-parameter> + </parameters> + </method> + <method name="_unregister" c:identifier="g_resources_unregister" moved-to="resources_unregister" version="2.32"> + <doc xml:space="preserve">Unregisters the resource from the process-global set of resources.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resource" transfer-ownership="none"> + <doc xml:space="preserve">A #GResource</doc> + <type name="Resource" c:type="GResource*"/> + </instance-parameter> + </parameters> + </method> + <method name="enumerate_children" c:identifier="g_resource_enumerate_children" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an array of constant strings</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="resource" transfer-ownership="none"> + <doc xml:space="preserve">A #GResource</doc> + <type name="Resource" c:type="GResource*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">A pathname inside the resource</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="lookup_flags" transfer-ownership="none"> + <doc xml:space="preserve">A #GResourceLookupFlags</doc> + <type name="ResourceLookupFlags" c:type="GResourceLookupFlags"/> + </parameter> + </parameters> + </method> + <method name="get_info" c:identifier="g_resource_get_info" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the file was found. %FALSE if there were errors</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="resource" transfer-ownership="none"> + <doc xml:space="preserve">A #GResource</doc> + <type name="Resource" c:type="GResource*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">A pathname inside the resource</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="lookup_flags" transfer-ownership="none"> + <doc xml:space="preserve">A #GResourceLookupFlags</doc> + <type name="ResourceLookupFlags" c:type="GResourceLookupFlags"/> + </parameter> + <parameter name="size" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to place the length of the contents of the file, + or %NULL if the length is not needed</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="flags" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to place the flags about the file, + or %NULL if the length is not needed</doc> + <type name="guint32" c:type="guint32*"/> + </parameter> + </parameters> + </method> + <method name="lookup_data" c:identifier="g_resource_lookup_data" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GBytes or %NULL on error. + Free the returned object with g_bytes_unref()</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <instance-parameter name="resource" transfer-ownership="none"> + <doc xml:space="preserve">A #GResource</doc> + <type name="Resource" c:type="GResource*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">A pathname inside the resource</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="lookup_flags" transfer-ownership="none"> + <doc xml:space="preserve">A #GResourceLookupFlags</doc> + <type name="ResourceLookupFlags" c:type="GResourceLookupFlags"/> + </parameter> + </parameters> + </method> + <method name="open_stream" c:identifier="g_resource_open_stream" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GInputStream or %NULL on error. + Free the returned object with g_object_unref()</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <instance-parameter name="resource" transfer-ownership="none"> + <doc xml:space="preserve">A #GResource</doc> + <type name="Resource" c:type="GResource*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">A pathname inside the resource</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="lookup_flags" transfer-ownership="none"> + <doc xml:space="preserve">A #GResourceLookupFlags</doc> + <type name="ResourceLookupFlags" c:type="GResourceLookupFlags"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_resource_ref" version="2.32"> + <doc xml:space="preserve">Atomically increments the reference count of @resource by one. This +function is MT-safe and may be called from any thread.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">The passed in #GResource</doc> + <type name="Resource" c:type="GResource*"/> + </return-value> + <parameters> + <instance-parameter name="resource" transfer-ownership="none"> + <doc xml:space="preserve">A #GResource</doc> + <type name="Resource" c:type="GResource*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_resource_unref" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resource" transfer-ownership="none"> + <doc xml:space="preserve">A #GResource</doc> + <type name="Resource" c:type="GResource*"/> + </instance-parameter> + </parameters> + </method> + <function name="load" c:identifier="g_resource_load" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GResource, or %NULL on error</doc> + <type name="Resource" c:type="GResource*"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">the path of a filename to load, in the GLib filename encoding</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + </record> + <enumeration name="ResourceError" version="2.32" glib:type-name="GResourceError" glib:get-type="g_resource_error_get_type" c:type="GResourceError" glib:error-domain="g-resource-error-quark"> + <doc xml:space="preserve">An error code used with %G_RESOURCE_ERROR in a #GError returned +from a #GResource routine.</doc> + <member name="not_found" value="0" c:identifier="G_RESOURCE_ERROR_NOT_FOUND" glib:nick="not-found"> + <doc xml:space="preserve">no file was found at the requested path</doc> + </member> + <member name="internal" value="1" c:identifier="G_RESOURCE_ERROR_INTERNAL" glib:nick="internal"> + <doc xml:space="preserve">unknown error</doc> + </member> + <function name="quark" c:identifier="g_resource_error_quark" version="2.32"> + <doc xml:space="preserve">Gets the #GResource Error Quark.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </return-value> + </function> + </enumeration> + <bitfield name="ResourceFlags" version="2.32" glib:type-name="GResourceFlags" glib:get-type="g_resource_flags_get_type" c:type="GResourceFlags"> + <doc xml:space="preserve">GResourceFlags give information about a particular file inside a resource +bundle.</doc> + <member name="none" value="0" c:identifier="G_RESOURCE_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + <member name="compressed" value="1" c:identifier="G_RESOURCE_FLAGS_COMPRESSED" glib:nick="compressed"> + <doc xml:space="preserve">The file is compressed.</doc> + </member> + </bitfield> + <bitfield name="ResourceLookupFlags" version="2.32" glib:type-name="GResourceLookupFlags" glib:get-type="g_resource_lookup_flags_get_type" c:type="GResourceLookupFlags"> + <doc xml:space="preserve">GResourceLookupFlags determine how resource path lookups are handled.</doc> + <member name="none" value="0" c:identifier="G_RESOURCE_LOOKUP_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags set.</doc> + </member> + </bitfield> + <function-macro name="SEEKABLE" c:identifier="G_SEEKABLE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SEEKABLE_GET_IFACE" c:identifier="G_SEEKABLE_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SETTINGS" c:identifier="G_SETTINGS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SETTINGS_BACKEND" c:identifier="G_SETTINGS_BACKEND" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SETTINGS_BACKEND_CLASS" c:identifier="G_SETTINGS_BACKEND_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <constant name="SETTINGS_BACKEND_EXTENSION_POINT_NAME" value="gsettings-backend" c:type="G_SETTINGS_BACKEND_EXTENSION_POINT_NAME"> + <doc xml:space="preserve">Extension point for #GSettingsBackend functionality.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="SETTINGS_BACKEND_GET_CLASS" c:identifier="G_SETTINGS_BACKEND_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SETTINGS_CLASS" c:identifier="G_SETTINGS_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SETTINGS_GET_CLASS" c:identifier="G_SETTINGS_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SIMPLE_ACTION" c:identifier="G_SIMPLE_ACTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SIMPLE_ACTION_GROUP" c:identifier="G_SIMPLE_ACTION_GROUP" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SIMPLE_ACTION_GROUP_CLASS" c:identifier="G_SIMPLE_ACTION_GROUP_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SIMPLE_ACTION_GROUP_GET_CLASS" c:identifier="G_SIMPLE_ACTION_GROUP_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SIMPLE_ASYNC_RESULT" c:identifier="G_SIMPLE_ASYNC_RESULT" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SIMPLE_ASYNC_RESULT_CLASS" c:identifier="G_SIMPLE_ASYNC_RESULT_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SIMPLE_ASYNC_RESULT_GET_CLASS" c:identifier="G_SIMPLE_ASYNC_RESULT_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SIMPLE_IO_STREAM" c:identifier="G_SIMPLE_IO_STREAM" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SIMPLE_PERMISSION" c:identifier="G_SIMPLE_PERMISSION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SIMPLE_PROXY_RESOLVER" c:identifier="G_SIMPLE_PROXY_RESOLVER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SIMPLE_PROXY_RESOLVER_CLASS" c:identifier="G_SIMPLE_PROXY_RESOLVER_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SIMPLE_PROXY_RESOLVER_GET_CLASS" c:identifier="G_SIMPLE_PROXY_RESOLVER_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET" c:identifier="G_SOCKET" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_ADDRESS" c:identifier="G_SOCKET_ADDRESS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_ADDRESS_CLASS" c:identifier="G_SOCKET_ADDRESS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_ADDRESS_ENUMERATOR" c:identifier="G_SOCKET_ADDRESS_ENUMERATOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_ADDRESS_ENUMERATOR_CLASS" c:identifier="G_SOCKET_ADDRESS_ENUMERATOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_ADDRESS_ENUMERATOR_GET_CLASS" c:identifier="G_SOCKET_ADDRESS_ENUMERATOR_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_ADDRESS_GET_CLASS" c:identifier="G_SOCKET_ADDRESS_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_CLASS" c:identifier="G_SOCKET_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_CLIENT" c:identifier="G_SOCKET_CLIENT" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_CLIENT_CLASS" c:identifier="G_SOCKET_CLIENT_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_CLIENT_GET_CLASS" c:identifier="G_SOCKET_CLIENT_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_CONNECTABLE" c:identifier="G_SOCKET_CONNECTABLE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_CONNECTABLE_GET_IFACE" c:identifier="G_SOCKET_CONNECTABLE_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_CONNECTION" c:identifier="G_SOCKET_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_CONNECTION_CLASS" c:identifier="G_SOCKET_CONNECTION_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_CONNECTION_GET_CLASS" c:identifier="G_SOCKET_CONNECTION_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_CONTROL_MESSAGE" c:identifier="G_SOCKET_CONTROL_MESSAGE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_CONTROL_MESSAGE_CLASS" c:identifier="G_SOCKET_CONTROL_MESSAGE_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_CONTROL_MESSAGE_GET_CLASS" c:identifier="G_SOCKET_CONTROL_MESSAGE_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_GET_CLASS" c:identifier="G_SOCKET_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_LISTENER" c:identifier="G_SOCKET_LISTENER" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_LISTENER_CLASS" c:identifier="G_SOCKET_LISTENER_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_LISTENER_GET_CLASS" c:identifier="G_SOCKET_LISTENER_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_SERVICE" c:identifier="G_SOCKET_SERVICE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_SERVICE_CLASS" c:identifier="G_SOCKET_SERVICE_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SOCKET_SERVICE_GET_CLASS" c:identifier="G_SOCKET_SERVICE_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SUBPROCESS" c:identifier="G_SUBPROCESS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SUBPROCESS_LAUNCHER" c:identifier="G_SUBPROCESS_LAUNCHER" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <interface name="Seekable" c:symbol-prefix="seekable" c:type="GSeekable" glib:type-name="GSeekable" glib:get-type="g_seekable_get_type" glib:type-struct="SeekableIface"> + <doc xml:space="preserve">#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.</doc> + <virtual-method name="can_seek" invoker="can_seek"> + <doc xml:space="preserve">Tests if the stream supports the #GSeekableIface.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @seekable can be seeked. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="seekable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekable.</doc> + <type name="Seekable" c:type="GSeekable*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="can_truncate" invoker="can_truncate"> + <doc xml:space="preserve">Tests if the length of the stream can be adjusted with +g_seekable_truncate().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the stream can be truncated, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="seekable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekable.</doc> + <type name="Seekable" c:type="GSeekable*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="seek" invoker="seek" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful. If an error + has occurred, this function will return %FALSE and set @error + appropriately if present.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="seekable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekable.</doc> + <type name="Seekable" c:type="GSeekable*"/> + </instance-parameter> + <parameter name="offset" transfer-ownership="none"> + <doc xml:space="preserve">a #goffset.</doc> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekType.</doc> + <type name="GLib.SeekType" c:type="GSeekType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="tell" invoker="tell"> + <doc xml:space="preserve">Tells the current position within the stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the offset from the beginning of the buffer.</doc> + <type name="gint64" c:type="goffset"/> + </return-value> + <parameters> + <instance-parameter name="seekable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekable.</doc> + <type name="Seekable" c:type="GSeekable*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="truncate_fn" invoker="truncate" throws="1"> + <doc xml:space="preserve">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 +previously 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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful. If an error + has occurred, this function will return %FALSE and set @error + appropriately if present.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="seekable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekable.</doc> + <type name="Seekable" c:type="GSeekable*"/> + </instance-parameter> + <parameter name="offset" transfer-ownership="none"> + <doc xml:space="preserve">new length for @seekable, in bytes.</doc> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <method name="can_seek" c:identifier="g_seekable_can_seek"> + <doc xml:space="preserve">Tests if the stream supports the #GSeekableIface.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @seekable can be seeked. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="seekable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekable.</doc> + <type name="Seekable" c:type="GSeekable*"/> + </instance-parameter> + </parameters> + </method> + <method name="can_truncate" c:identifier="g_seekable_can_truncate"> + <doc xml:space="preserve">Tests if the length of the stream can be adjusted with +g_seekable_truncate().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the stream can be truncated, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="seekable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekable.</doc> + <type name="Seekable" c:type="GSeekable*"/> + </instance-parameter> + </parameters> + </method> + <method name="seek" c:identifier="g_seekable_seek" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful. If an error + has occurred, this function will return %FALSE and set @error + appropriately if present.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="seekable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekable.</doc> + <type name="Seekable" c:type="GSeekable*"/> + </instance-parameter> + <parameter name="offset" transfer-ownership="none"> + <doc xml:space="preserve">a #goffset.</doc> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekType.</doc> + <type name="GLib.SeekType" c:type="GSeekType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="tell" c:identifier="g_seekable_tell"> + <doc xml:space="preserve">Tells the current position within the stream.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the offset from the beginning of the buffer.</doc> + <type name="gint64" c:type="goffset"/> + </return-value> + <parameters> + <instance-parameter name="seekable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekable.</doc> + <type name="Seekable" c:type="GSeekable*"/> + </instance-parameter> + </parameters> + </method> + <method name="truncate" c:identifier="g_seekable_truncate" throws="1"> + <doc xml:space="preserve">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 +previously 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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful. If an error + has occurred, this function will return %FALSE and set @error + appropriately if present.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="seekable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekable.</doc> + <type name="Seekable" c:type="GSeekable*"/> + </instance-parameter> + <parameter name="offset" transfer-ownership="none"> + <doc xml:space="preserve">new length for @seekable, in bytes.</doc> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + </interface> + <record name="SeekableIface" c:type="GSeekableIface" glib:is-gtype-struct-for="Seekable"> + <doc xml:space="preserve">Provides an interface for implementing seekable functionality on I/O Streams.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="tell"> + <callback name="tell"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the offset from the beginning of the buffer.</doc> + <type name="gint64" c:type="goffset"/> + </return-value> + <parameters> + <parameter name="seekable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekable.</doc> + <type name="Seekable" c:type="GSeekable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_seek"> + <callback name="can_seek"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @seekable can be seeked. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="seekable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekable.</doc> + <type name="Seekable" c:type="GSeekable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="seek"> + <callback name="seek" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful. If an error + has occurred, this function will return %FALSE and set @error + appropriately if present.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="seekable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekable.</doc> + <type name="Seekable" c:type="GSeekable*"/> + </parameter> + <parameter name="offset" transfer-ownership="none"> + <doc xml:space="preserve">a #goffset.</doc> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekType.</doc> + <type name="GLib.SeekType" c:type="GSeekType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_truncate"> + <callback name="can_truncate"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the stream can be truncated, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="seekable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekable.</doc> + <type name="Seekable" c:type="GSeekable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="truncate_fn"> + <callback name="truncate_fn" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful. If an error + has occurred, this function will return %FALSE and set @error + appropriately if present.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="seekable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSeekable.</doc> + <type name="Seekable" c:type="GSeekable*"/> + </parameter> + <parameter name="offset" transfer-ownership="none"> + <doc xml:space="preserve">new length for @seekable, in bytes.</doc> + <type name="gint64" c:type="goffset"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="Settings" c:symbol-prefix="settings" c:type="GSettings" parent="GObject.Object" glib:type-name="GSettings" glib:get-type="g_settings_get_type" glib:type-struct="SettingsClass"> + <doc xml:space="preserve">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`.</doc> + <constructor name="new" c:identifier="g_settings_new" version="2.26"> + <doc xml:space="preserve">Creates a new #GSettings object with the schema specified by +@schema_id. + +It is an error for the schema to not exist: schemas are an +essential part of a program, as they provide type information. +If schemas need to be dynamically loaded (for example, from an +optional runtime dependency), g_settings_schema_source_lookup() +can be used to test for their existence before loading them. + +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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </return-value> + <parameters> + <parameter name="schema_id" transfer-ownership="none"> + <doc xml:space="preserve">the id of the schema</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_full" c:identifier="g_settings_new_full" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </return-value> + <parameters> + <parameter name="schema" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchema</doc> + <type name="SettingsSchema" c:type="GSettingsSchema*"/> + </parameter> + <parameter name="backend" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GSettingsBackend</doc> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </parameter> + <parameter name="path" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the path to use</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_with_backend" c:identifier="g_settings_new_with_backend" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </return-value> + <parameters> + <parameter name="schema_id" transfer-ownership="none"> + <doc xml:space="preserve">the id of the schema</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GSettingsBackend to use</doc> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_with_backend_and_path" c:identifier="g_settings_new_with_backend_and_path" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </return-value> + <parameters> + <parameter name="schema_id" transfer-ownership="none"> + <doc xml:space="preserve">the id of the schema</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GSettingsBackend to use</doc> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the path to use</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_with_path" c:identifier="g_settings_new_with_path" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </return-value> + <parameters> + <parameter name="schema_id" transfer-ownership="none"> + <doc xml:space="preserve">the id of the schema</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the path to use</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <function name="list_relocatable_schemas" c:identifier="g_settings_list_relocatable_schemas" version="2.28" deprecated="1" deprecated-version="2.40"> + <doc xml:space="preserve">Deprecated.</doc> + <doc-deprecated xml:space="preserve">Use g_settings_schema_source_list_schemas() instead</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a list of relocatable + #GSettings schemas that are available, in no defined order. The list must + not be modified or freed.</doc> + <array c:type="const gchar* const*"> + <type name="utf8"/> + </array> + </return-value> + </function> + <function name="list_schemas" c:identifier="g_settings_list_schemas" version="2.26" deprecated="1" deprecated-version="2.40"> + <doc xml:space="preserve">Deprecated.</doc> + <doc-deprecated xml:space="preserve">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.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a list of #GSettings + schemas that are available, in no defined order. The list must not be + modified or freed.</doc> + <array c:type="const gchar* const*"> + <type name="utf8"/> + </array> + </return-value> + </function> + <function name="sync" c:identifier="g_settings_sync"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </function> + <function name="unbind" c:identifier="g_settings_unbind" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">the object</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + <parameter name="property" transfer-ownership="none"> + <doc xml:space="preserve">the property whose binding is removed</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <virtual-method name="change_event"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="keys" transfer-ownership="none"> + <type name="GLib.Quark" c:type="const GQuark*"/> + </parameter> + <parameter name="n_keys" transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="writable_change_event"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="writable_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <method name="apply" c:identifier="g_settings_apply"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings instance</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + </parameters> + </method> + <method name="bind" c:identifier="g_settings_bind" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to bind</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + <parameter name="property" transfer-ownership="none"> + <doc xml:space="preserve">the name of the property to bind</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the binding</doc> + <type name="SettingsBindFlags" c:type="GSettingsBindFlags"/> + </parameter> + </parameters> + </method> + <method name="bind_with_mapping" c:identifier="g_settings_bind_with_mapping" version="2.26" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to bind</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + <parameter name="property" transfer-ownership="none"> + <doc xml:space="preserve">the name of the property to bind</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags for the binding</doc> + <type name="SettingsBindFlags" c:type="GSettingsBindFlags"/> + </parameter> + <parameter name="get_mapping" transfer-ownership="none"> + <doc xml:space="preserve">a function that gets called to convert values + from @settings to @object, or %NULL to use the default GIO mapping</doc> + <type name="SettingsBindGetMapping" c:type="GSettingsBindGetMapping"/> + </parameter> + <parameter name="set_mapping" transfer-ownership="none" scope="notified" closure="6" destroy="7"> + <doc xml:space="preserve">a function that gets called to convert values + from @object to @settings, or %NULL to use the default GIO mapping</doc> + <type name="SettingsBindSetMapping" c:type="GSettingsBindSetMapping"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data that gets passed to @get_mapping and @set_mapping</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">#GDestroyNotify function for @user_data</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="bind_writable" c:identifier="g_settings_bind_writable" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to bind</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + <parameter name="property" transfer-ownership="none"> + <doc xml:space="preserve">the name of a boolean property to bind</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="inverted" transfer-ownership="none"> + <doc xml:space="preserve">whether to 'invert' the value</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="create_action" c:identifier="g_settings_create_action" version="2.32"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GAction</doc> + <type name="Action" c:type="GAction*"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the name of a key in @settings</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="delay" c:identifier="g_settings_delay" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + </parameters> + </method> + <method name="get" c:identifier="g_settings_get" version="2.26" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to get the value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">arguments as per @format</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="get_boolean" c:identifier="g_settings_get_boolean" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a boolean</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to get the value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_child" c:identifier="g_settings_get_child" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a 'child' settings object</doc> + <type name="Settings" c:type="GSettings*"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the child schema</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_default_value" c:identifier="g_settings_get_default_value" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the default value</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to get the default value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_double" c:identifier="g_settings_get_double" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a double</doc> + <type name="gdouble" c:type="gdouble"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to get the value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_enum" c:identifier="g_settings_get_enum" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the enum value</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to get the value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_flags" c:identifier="g_settings_get_flags" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the flags value</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to get the value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_has_unapplied" c:identifier="g_settings_get_has_unapplied" version="2.26"> + <doc xml:space="preserve">Returns whether the #GSettings object has any unapplied +changes. This can only be the case if it is in 'delayed-apply' mode.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @settings has unapplied changes</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_int" c:identifier="g_settings_get_int" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an integer</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to get the value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_int64" c:identifier="g_settings_get_int64" version="2.50"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a 64-bit integer</doc> + <type name="gint64" c:type="gint64"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to get the value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_mapped" c:identifier="g_settings_get_mapped"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the result, which may be %NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to get the value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="mapping" transfer-ownership="none" scope="call" closure="2"> + <doc xml:space="preserve">the function to map the value in the + settings database to the value used by the application</doc> + <type name="SettingsGetMapping" c:type="GSettingsGetMapping"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data for @mapping</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="get_range" c:identifier="g_settings_get_range" version="2.28" deprecated="1" deprecated-version="2.40"> + <doc xml:space="preserve">Queries the range of a key.</doc> + <doc-deprecated xml:space="preserve">Use g_settings_schema_key_get_range() instead.</doc-deprecated> + <return-value transfer-ownership="full"> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to query the range of</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_string" c:identifier="g_settings_get_string" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly-allocated string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to get the value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_strv" c:identifier="g_settings_get_strv" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a +newly-allocated, %NULL-terminated array of strings, the value that +is stored at @key in @settings.</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to get the value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_uint" c:identifier="g_settings_get_uint" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an unsigned integer</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to get the value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_uint64" c:identifier="g_settings_get_uint64" version="2.50"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a 64-bit unsigned integer</doc> + <type name="guint64" c:type="guint64"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to get the value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_user_value" c:identifier="g_settings_get_user_value" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the user's value, if set</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to get the user value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_value" c:identifier="g_settings_get_value" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GVariant</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to get the value for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="is_writable" c:identifier="g_settings_is_writable" version="2.26"> + <doc xml:space="preserve">Finds out if a key can be written or not</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the key @name is writable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="list_children" c:identifier="g_settings_list_children"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a list of the children on + @settings, in no defined order</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + </parameters> + </method> + <method name="list_keys" c:identifier="g_settings_list_keys" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_settings_schema_list_keys() instead.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a list of the keys on + @settings, in no defined order</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + </parameters> + </method> + <method name="range_check" c:identifier="g_settings_range_check" version="2.28" deprecated="1" deprecated-version="2.40"> + <doc xml:space="preserve">Checks if the given @value is of the correct type and within the +permitted range for @key.</doc> + <doc-deprecated xml:space="preserve">Use g_settings_schema_key_range_check() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @value is valid for @key</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key to check</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value to check</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="reset" c:identifier="g_settings_reset"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the name of a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="revert" c:identifier="g_settings_revert"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings instance</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + </parameters> + </method> + <method name="set" c:identifier="g_settings_set" version="2.26" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if setting the key succeeded, + %FALSE if the key was not writable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the name of the key to set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant format string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">arguments as per @format</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="set_boolean" c:identifier="g_settings_set_boolean" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if setting the key succeeded, + %FALSE if the key was not writable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the name of the key to set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value to set it to</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_double" c:identifier="g_settings_set_double" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if setting the key succeeded, + %FALSE if the key was not writable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the name of the key to set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value to set it to</doc> + <type name="gdouble" c:type="gdouble"/> + </parameter> + </parameters> + </method> + <method name="set_enum" c:identifier="g_settings_set_enum"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE, if the set succeeds</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key, within @settings</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">an enumerated value</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="set_flags" c:identifier="g_settings_set_flags"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE, if the set succeeds</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a key, within @settings</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a flags value</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="set_int" c:identifier="g_settings_set_int" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if setting the key succeeded, + %FALSE if the key was not writable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the name of the key to set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value to set it to</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="set_int64" c:identifier="g_settings_set_int64" version="2.50"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if setting the key succeeded, + %FALSE if the key was not writable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the name of the key to set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value to set it to</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + </parameters> + </method> + <method name="set_string" c:identifier="g_settings_set_string" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if setting the key succeeded, + %FALSE if the key was not writable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the name of the key to set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value to set it to</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_strv" c:identifier="g_settings_set_strv" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if setting the key succeeded, + %FALSE if the key was not writable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the name of the key to set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the value to set it to, or %NULL</doc> + <array c:type="const gchar* const*"> + <type name="utf8" c:type="gchar*"/> + </array> + </parameter> + </parameters> + </method> + <method name="set_uint" c:identifier="g_settings_set_uint" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if setting the key succeeded, + %FALSE if the key was not writable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the name of the key to set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value to set it to</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="set_uint64" c:identifier="g_settings_set_uint64" version="2.50"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if setting the key succeeded, + %FALSE if the key was not writable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the name of the key to set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value to set it to</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + </parameters> + </method> + <method name="set_value" c:identifier="g_settings_set_value" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if setting the key succeeded, + %FALSE if the key was not writable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="settings" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettings object</doc> + <type name="Settings" c:type="GSettings*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the name of the key to set</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant of the correct type</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <property name="backend" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The name of the context that the settings are stored in.</doc> + <type name="SettingsBackend"/> + </property> + <property name="delay-apply" version="2.28" transfer-ownership="none"> + <doc xml:space="preserve">Whether the #GSettings object is in 'delay-apply' mode. See +g_settings_delay() for details.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="has-unapplied" transfer-ownership="none"> + <doc xml:space="preserve">If this property is %TRUE, the #GSettings object has outstanding +changes that will be applied when g_settings_apply() is called.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="path" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The path within the backend where the settings are stored.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="schema" deprecated="1" deprecated-version="2.32" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use the 'schema-id' property instead. In a future +version, this property may instead refer to a #GSettingsSchema.</doc-deprecated> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="schema-id" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The name of the schema that describes the types of keys +for this #GSettings object.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="settings-schema" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="SettingsSchema"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv"> + <type name="SettingsPrivate" c:type="GSettingsPrivate*"/> + </field> + <glib:signal name="change-event" when="last"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop other handlers from being invoked for the + event. FALSE to propagate the event further.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="keys" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve"> + an array of #GQuarks for the changed keys, or %NULL</doc> + <array length="1" zero-terminated="0" c:type="gpointer"> + <type name="GLib.Quark"/> + </array> + </parameter> + <parameter name="n_keys" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @keys array, or 0</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="changed" when="last" detailed="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the name of the key that changed</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="writable-change-event" when="last"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop other handlers from being invoked for the + event. FALSE to propagate the event further.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the quark of the key, or 0</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="writable-changed" when="last" detailed="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the key</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </glib:signal> + </class> + <class name="SettingsBackend" c:symbol-prefix="settings_backend" c:type="GSettingsBackend" parent="GObject.Object" abstract="1" glib:type-name="GSettingsBackend" glib:get-type="g_settings_backend_get_type" glib:type-struct="SettingsBackendClass"> + <doc xml:space="preserve">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`.</doc> + <function name="flatten_tree" c:identifier="g_settings_backend_flatten_tree" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="tree" transfer-ownership="none"> + <doc xml:space="preserve">a #GTree containing the changes</doc> + <type name="GLib.Tree" c:type="GTree*"/> + </parameter> + <parameter name="path" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the location to save the path</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="keys" direction="out" caller-allocates="0" transfer-ownership="container"> + <doc xml:space="preserve">the + location to save the relative keys</doc> + <array c:type="const gchar***"> + <type name="utf8" c:type="gchar**"/> + </array> + </parameter> + <parameter name="values" direction="out" caller-allocates="0" transfer-ownership="container" optional="1" allow-none="1"> + <doc xml:space="preserve"> + the location to save the values, or %NULL</doc> + <array c:type="GVariant***"> + <type name="GLib.Variant" c:type="GVariant**"/> + </array> + </parameter> + </parameters> + </function> + <function name="get_default" c:identifier="g_settings_backend_get_default" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the default #GSettingsBackend, + which will be a dummy (memory) settings backend if no other settings + backend is available.</doc> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </return-value> + </function> + <virtual-method name="get_permission" introspectable="0"> + <return-value> + <type name="Permission" c:type="GPermission*"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_writable"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="read"> + <return-value transfer-ownership="full"> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="expected_type" transfer-ownership="none"> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="read_user_value"> + <return-value transfer-ownership="full"> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="expected_type" transfer-ownership="none"> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="reset"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="origin_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="subscribe"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="sync"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="unsubscribe"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="write"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="origin_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="write_tree"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </instance-parameter> + <parameter name="tree" transfer-ownership="none"> + <type name="GLib.Tree" c:type="GTree*"/> + </parameter> + <parameter name="origin_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <method name="changed" c:identifier="g_settings_backend_changed" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsBackend implementation</doc> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the name of the key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="origin_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the origin tag</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="changed_tree" c:identifier="g_settings_backend_changed_tree" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsBackend implementation</doc> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </instance-parameter> + <parameter name="tree" transfer-ownership="none"> + <doc xml:space="preserve">a #GTree containing the changes</doc> + <type name="GLib.Tree" c:type="GTree*"/> + </parameter> + <parameter name="origin_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the origin tag</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="keys_changed" c:identifier="g_settings_backend_keys_changed" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsBackend implementation</doc> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the path containing the changes</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="items" transfer-ownership="none"> + <doc xml:space="preserve">the %NULL-terminated list of changed keys</doc> + <array c:type="const gchar* const*"> + <type name="utf8" c:type="gchar*"/> + </array> + </parameter> + <parameter name="origin_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the origin tag</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="path_changed" c:identifier="g_settings_backend_path_changed" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsBackend implementation</doc> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the path containing the changes</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="origin_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the origin tag</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="path_writable_changed" c:identifier="g_settings_backend_path_writable_changed" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsBackend implementation</doc> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the name of the path</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="writable_changed" c:identifier="g_settings_backend_writable_changed" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsBackend implementation</doc> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">the name of the key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="SettingsBackendPrivate" c:type="GSettingsBackendPrivate*"/> + </field> + </class> + <record name="SettingsBackendClass" c:type="GSettingsBackendClass" glib:is-gtype-struct-for="SettingsBackend"> + <doc xml:space="preserve">Class structure for #GSettingsBackend.</doc> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="read"> + <callback name="read"> + <return-value transfer-ownership="full"> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="expected_type" transfer-ownership="none"> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_writable"> + <callback name="get_writable"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="write"> + <callback name="write"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="origin_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="write_tree"> + <callback name="write_tree"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </parameter> + <parameter name="tree" transfer-ownership="none"> + <type name="GLib.Tree" c:type="GTree*"/> + </parameter> + <parameter name="origin_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="reset"> + <callback name="reset"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="origin_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="subscribe"> + <callback name="subscribe"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="unsubscribe"> + <callback name="unsubscribe"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="sync"> + <callback name="sync"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_permission" introspectable="0"> + <callback name="get_permission" introspectable="0"> + <return-value> + <type name="Permission" c:type="GPermission*"/> + </return-value> + <parameters> + <parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="read_user_value"> + <callback name="read_user_value"> + <return-value transfer-ownership="full"> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="backend" transfer-ownership="none"> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="expected_type" transfer-ownership="none"> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="23"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <record name="SettingsBackendPrivate" c:type="GSettingsBackendPrivate" disguised="1"/> + <bitfield name="SettingsBindFlags" glib:type-name="GSettingsBindFlags" glib:get-type="g_settings_bind_flags_get_type" c:type="GSettingsBindFlags"> + <doc xml:space="preserve">Flags used when creating a binding. These flags determine in which +direction the binding works. The default is to synchronize in both +directions.</doc> + <member name="default" value="0" c:identifier="G_SETTINGS_BIND_DEFAULT" glib:nick="default"> + <doc xml:space="preserve">Equivalent to `G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET`</doc> + </member> + <member name="get" value="1" c:identifier="G_SETTINGS_BIND_GET" glib:nick="get"> + <doc xml:space="preserve">Update the #GObject property when the setting changes. + It is an error to use this flag if the property is not writable.</doc> + </member> + <member name="set" value="2" c:identifier="G_SETTINGS_BIND_SET" glib:nick="set"> + <doc xml:space="preserve">Update the setting when the #GObject property changes. + It is an error to use this flag if the property is not readable.</doc> + </member> + <member name="no_sensitivity" value="4" c:identifier="G_SETTINGS_BIND_NO_SENSITIVITY" glib:nick="no-sensitivity"> + <doc xml:space="preserve">Do not try to bind a "sensitivity" property to the writability of the setting</doc> + </member> + <member name="get_no_changes" value="8" c:identifier="G_SETTINGS_BIND_GET_NO_CHANGES" glib:nick="get-no-changes"> + <doc xml:space="preserve">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</doc> + </member> + <member name="invert_boolean" value="16" c:identifier="G_SETTINGS_BIND_INVERT_BOOLEAN" glib:nick="invert-boolean"> + <doc xml:space="preserve">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().</doc> + </member> + </bitfield> + <callback name="SettingsBindGetMapping" c:type="GSettingsBindGetMapping"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the conversion succeeded, %FALSE in case of an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">return location for the property value</doc> + <type name="GObject.Value" c:type="GValue*"/> + </parameter> + <parameter name="variant" transfer-ownership="none"> + <doc xml:space="preserve">the #GVariant</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">user data that was specified when the binding was created</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <callback name="SettingsBindSetMapping" c:type="GSettingsBindSetMapping"> + <doc xml:space="preserve">The type for the function that is used to convert an object property +value to a #GVariant for storing it in #GSettings.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GVariant holding the data from @value, + or %NULL in case of an error</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GValue containing the property value to map</doc> + <type name="GObject.Value" c:type="const GValue*"/> + </parameter> + <parameter name="expected_type" transfer-ownership="none"> + <doc xml:space="preserve">the #GVariantType to create</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">user data that was specified when the binding was created</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="SettingsClass" c:type="GSettingsClass" glib:is-gtype-struct-for="Settings"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="writable_changed"> + <callback name="writable_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="settings" transfer-ownership="none"> + <type name="Settings" c:type="GSettings*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="changed"> + <callback name="changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="settings" transfer-ownership="none"> + <type name="Settings" c:type="GSettings*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="writable_change_event"> + <callback name="writable_change_event"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="settings" transfer-ownership="none"> + <type name="Settings" c:type="GSettings*"/> + </parameter> + <parameter name="key" transfer-ownership="none"> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + </parameters> + </callback> + </field> + <field name="change_event"> + <callback name="change_event"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="settings" transfer-ownership="none"> + <type name="Settings" c:type="GSettings*"/> + </parameter> + <parameter name="keys" transfer-ownership="none"> + <type name="GLib.Quark" c:type="const GQuark*"/> + </parameter> + <parameter name="n_keys" transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </callback> + </field> + <field name="padding"> + <array zero-terminated="0" fixed-size="20"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <callback name="SettingsGetMapping" c:type="GSettingsGetMapping"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the conversion succeeded, %FALSE in case of an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the #GVariant to map, or %NULL</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="result" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the result of the mapping</doc> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">the user data that was passed to +g_settings_get_mapped()</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <record name="SettingsPrivate" c:type="GSettingsPrivate" disguised="1"/> + <record name="SettingsSchema" c:type="GSettingsSchema" version="2.32" glib:type-name="GSettingsSchema" glib:get-type="g_settings_schema_get_type" c:symbol-prefix="settings_schema"> + <doc xml:space="preserve">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.</doc> + <method name="get_id" c:identifier="g_settings_schema_get_id"> + <doc xml:space="preserve">Get the ID of @schema.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the ID</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="schema" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchema</doc> + <type name="SettingsSchema" c:type="GSettingsSchema*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_key" c:identifier="g_settings_schema_get_key" version="2.40"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the #GSettingsSchemaKey for @name</doc> + <type name="SettingsSchemaKey" c:type="GSettingsSchemaKey*"/> + </return-value> + <parameters> + <instance-parameter name="schema" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchema</doc> + <type name="SettingsSchema" c:type="GSettingsSchema*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="get_path" c:identifier="g_settings_schema_get_path" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the path of the schema, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="schema" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchema</doc> + <type name="SettingsSchema" c:type="GSettingsSchema*"/> + </instance-parameter> + </parameters> + </method> + <method name="has_key" c:identifier="g_settings_schema_has_key" version="2.40"> + <doc xml:space="preserve">Checks if @schema has a key named @name.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if such a key exists</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="schema" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchema</doc> + <type name="SettingsSchema" c:type="GSettingsSchema*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of a key</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="list_children" c:identifier="g_settings_schema_list_children" version="2.44"> + <doc xml:space="preserve">Gets the list of children in @schema. + +You should free the return value with g_strfreev() when you are done +with it.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a list of the children on + @settings, in no defined order</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="schema" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchema</doc> + <type name="SettingsSchema" c:type="GSettingsSchema*"/> + </instance-parameter> + </parameters> + </method> + <method name="list_keys" c:identifier="g_settings_schema_list_keys" version="2.46"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a list of the keys on + @schema, in no defined order</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="schema" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchema</doc> + <type name="SettingsSchema" c:type="GSettingsSchema*"/> + </instance-parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_settings_schema_ref" version="2.32"> + <doc xml:space="preserve">Increase the reference count of @schema, returning a new reference.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new reference to @schema</doc> + <type name="SettingsSchema" c:type="GSettingsSchema*"/> + </return-value> + <parameters> + <instance-parameter name="schema" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchema</doc> + <type name="SettingsSchema" c:type="GSettingsSchema*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_settings_schema_unref" version="2.32"> + <doc xml:space="preserve">Decrease the reference count of @schema, possibly freeing it.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="schema" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchema</doc> + <type name="SettingsSchema" c:type="GSettingsSchema*"/> + </instance-parameter> + </parameters> + </method> + </record> + <record name="SettingsSchemaKey" c:type="GSettingsSchemaKey" glib:type-name="GSettingsSchemaKey" glib:get-type="g_settings_schema_key_get_type" c:symbol-prefix="settings_schema_key"> + <doc xml:space="preserve">#GSettingsSchemaKey is an opaque data structure and can only be accessed +using the following functions.</doc> + <method name="get_default_value" c:identifier="g_settings_schema_key_get_default_value" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the default value for the key</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchemaKey</doc> + <type name="SettingsSchemaKey" c:type="GSettingsSchemaKey*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_description" c:identifier="g_settings_schema_key_get_description" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the description for @key, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchemaKey</doc> + <type name="SettingsSchemaKey" c:type="GSettingsSchemaKey*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_name" c:identifier="g_settings_schema_key_get_name" version="2.44"> + <doc xml:space="preserve">Gets the name of @key.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the name of @key.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchemaKey</doc> + <type name="SettingsSchemaKey" c:type="GSettingsSchemaKey*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_range" c:identifier="g_settings_schema_key_get_range" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GVariant describing the range</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchemaKey</doc> + <type name="SettingsSchemaKey" c:type="GSettingsSchemaKey*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_summary" c:identifier="g_settings_schema_key_get_summary" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the summary for @key, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchemaKey</doc> + <type name="SettingsSchemaKey" c:type="GSettingsSchemaKey*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_value_type" c:identifier="g_settings_schema_key_get_value_type" version="2.40"> + <doc xml:space="preserve">Gets the #GVariantType of @key.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the type of @key</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <instance-parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchemaKey</doc> + <type name="SettingsSchemaKey" c:type="GSettingsSchemaKey*"/> + </instance-parameter> + </parameters> + </method> + <method name="range_check" c:identifier="g_settings_schema_key_range_check" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @value is valid for @key</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchemaKey</doc> + <type name="SettingsSchemaKey" c:type="GSettingsSchemaKey*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value to check</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_settings_schema_key_ref" version="2.40"> + <doc xml:space="preserve">Increase the reference count of @key, returning a new reference.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new reference to @key</doc> + <type name="SettingsSchemaKey" c:type="GSettingsSchemaKey*"/> + </return-value> + <parameters> + <instance-parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchemaKey</doc> + <type name="SettingsSchemaKey" c:type="GSettingsSchemaKey*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_settings_schema_key_unref" version="2.40"> + <doc xml:space="preserve">Decrease the reference count of @key, possibly freeing it.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchemaKey</doc> + <type name="SettingsSchemaKey" c:type="GSettingsSchemaKey*"/> + </instance-parameter> + </parameters> + </method> + </record> + <record name="SettingsSchemaSource" c:type="GSettingsSchemaSource" version="2.32" glib:type-name="GSettingsSchemaSource" glib:get-type="g_settings_schema_source_get_type" c:symbol-prefix="settings_schema_source"> + <doc xml:space="preserve">This is an opaque structure type. You may not access it directly.</doc> + <constructor name="new_from_directory" c:identifier="g_settings_schema_source_new_from_directory" version="2.32" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <type name="SettingsSchemaSource" c:type="GSettingsSchemaSource*"/> + </return-value> + <parameters> + <parameter name="directory" transfer-ownership="none"> + <doc xml:space="preserve">the filename of a directory</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="parent" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GSettingsSchemaSource, or %NULL</doc> + <type name="SettingsSchemaSource" c:type="GSettingsSchemaSource*"/> + </parameter> + <parameter name="trusted" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE, if the directory is trusted</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </constructor> + <method name="list_schemas" c:identifier="g_settings_schema_source_list_schemas" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchemaSource</doc> + <type name="SettingsSchemaSource" c:type="GSettingsSchemaSource*"/> + </instance-parameter> + <parameter name="recursive" transfer-ownership="none"> + <doc xml:space="preserve">if we should recurse</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="non_relocatable" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the + list of non-relocatable schemas, in no defined order</doc> + <array c:type="gchar***"> + <type name="utf8" c:type="gchar**"/> + </array> + </parameter> + <parameter name="relocatable" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the list + of relocatable schemas, in no defined order</doc> + <array c:type="gchar***"> + <type name="utf8" c:type="gchar**"/> + </array> + </parameter> + </parameters> + </method> + <method name="lookup" c:identifier="g_settings_schema_source_lookup" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a new #GSettingsSchema</doc> + <type name="SettingsSchema" c:type="GSettingsSchema*"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchemaSource</doc> + <type name="SettingsSchemaSource" c:type="GSettingsSchemaSource*"/> + </instance-parameter> + <parameter name="schema_id" transfer-ownership="none"> + <doc xml:space="preserve">a schema ID</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="recursive" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the lookup should be recursive</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="ref" c:identifier="g_settings_schema_source_ref" version="2.32"> + <doc xml:space="preserve">Increase the reference count of @source, returning a new reference.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new reference to @source</doc> + <type name="SettingsSchemaSource" c:type="GSettingsSchemaSource*"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchemaSource</doc> + <type name="SettingsSchemaSource" c:type="GSettingsSchemaSource*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="g_settings_schema_source_unref" version="2.32"> + <doc xml:space="preserve">Decrease the reference count of @source, possibly freeing it.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GSettingsSchemaSource</doc> + <type name="SettingsSchemaSource" c:type="GSettingsSchemaSource*"/> + </instance-parameter> + </parameters> + </method> + <function name="get_default" c:identifier="g_settings_schema_source_get_default" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the default schema source</doc> + <type name="SettingsSchemaSource" c:type="GSettingsSchemaSource*"/> + </return-value> + </function> + </record> + <class name="SimpleAction" c:symbol-prefix="simple_action" c:type="GSimpleAction" parent="GObject.Object" glib:type-name="GSimpleAction" glib:get-type="g_simple_action_get_type"> + <doc xml:space="preserve">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.</doc> + <implements name="Action"/> + <constructor name="new" c:identifier="g_simple_action_new" version="2.28"> + <doc xml:space="preserve">Creates a new action. + +The created action is stateless. See g_simple_action_new_stateful() to create +an action that has state.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSimpleAction</doc> + <type name="SimpleAction" c:type="GSimpleAction*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameter_type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the type of parameter that will be passed to + handlers for the #GSimpleAction::activate signal, or %NULL for no parameter</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_stateful" c:identifier="g_simple_action_new_stateful" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSimpleAction</doc> + <type name="SimpleAction" c:type="GSimpleAction*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="parameter_type" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the type of the parameter that will be passed to + handlers for the #GSimpleAction::activate signal, or %NULL for no parameter</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + <parameter name="state" transfer-ownership="none"> + <doc xml:space="preserve">the initial state of the action</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </constructor> + <method name="set_enabled" c:identifier="g_simple_action_set_enabled" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAction</doc> + <type name="SimpleAction" c:type="GSimpleAction*"/> + </instance-parameter> + <parameter name="enabled" transfer-ownership="none"> + <doc xml:space="preserve">whether the action is enabled</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_state" c:identifier="g_simple_action_set_state" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAction</doc> + <type name="SimpleAction" c:type="GSimpleAction*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the new #GVariant for the state</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="set_state_hint" c:identifier="g_simple_action_set_state_hint" version="2.44"> + <doc xml:space="preserve">Sets the state hint for the action. + +See g_action_get_state_hint() for more information about +action state hints.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAction</doc> + <type name="SimpleAction" c:type="GSimpleAction*"/> + </instance-parameter> + <parameter name="state_hint" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant representing the state hint</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <property name="enabled" version="2.28" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">If @action is currently enabled. + +If the action is disabled then calls to g_action_activate() and +g_action_change_state() have no effect.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="name" version="2.28" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The name of the action. This is mostly meaningful for identifying +the action once it has been added to a #GSimpleActionGroup.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="parameter-type" version="2.28" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The type of the parameter that must be given when activating the +action.</doc> + <type name="GLib.VariantType"/> + </property> + <property name="state" version="2.28" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">The state of the action, or %NULL if the action is stateless.</doc> + <type name="GLib.Variant"/> + </property> + <property name="state-type" version="2.28" transfer-ownership="none"> + <doc xml:space="preserve">The #GVariantType of the state that the action has, or %NULL if the +action is stateless.</doc> + <type name="GLib.VariantType"/> + </property> + <glib:signal name="activate" when="last" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="parameter" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the parameter to the activation, or %NULL if it has + no parameter</doc> + <type name="GLib.Variant"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="change-state" when="last" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the requested value for the state</doc> + <type name="GLib.Variant"/> + </parameter> + </parameters> + </glib:signal> + </class> + <class name="SimpleActionGroup" c:symbol-prefix="simple_action_group" c:type="GSimpleActionGroup" version="2.28" parent="GObject.Object" glib:type-name="GSimpleActionGroup" glib:get-type="g_simple_action_group_get_type" glib:type-struct="SimpleActionGroupClass"> + <doc xml:space="preserve">#GSimpleActionGroup is a hash table filled with #GAction objects, +implementing the #GActionGroup and #GActionMap interfaces.</doc> + <implements name="ActionGroup"/> + <implements name="ActionMap"/> + <constructor name="new" c:identifier="g_simple_action_group_new" version="2.28"> + <doc xml:space="preserve">Creates a new, empty, #GSimpleActionGroup.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSimpleActionGroup</doc> + <type name="SimpleActionGroup" c:type="GSimpleActionGroup*"/> + </return-value> + </constructor> + <method name="add_entries" c:identifier="g_simple_action_group_add_entries" version="2.30" deprecated="1" deprecated-version="2.38"> + <doc xml:space="preserve">A convenience function for creating multiple #GSimpleAction instances +and adding them to the action group.</doc> + <doc-deprecated xml:space="preserve">Use g_action_map_add_action_entries()</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleActionGroup</doc> + <type name="SimpleActionGroup" c:type="GSimpleActionGroup*"/> + </instance-parameter> + <parameter name="entries" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to the first item in + an array of #GActionEntry structs</doc> + <array length="1" zero-terminated="0" c:type="const GActionEntry*"> + <type name="ActionEntry" c:type="GActionEntry"/> + </array> + </parameter> + <parameter name="n_entries" transfer-ownership="none"> + <doc xml:space="preserve">the length of @entries, or -1</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the user data for signal connections</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="insert" c:identifier="g_simple_action_group_insert" version="2.28" deprecated="1" deprecated-version="2.38"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_action_map_add_action()</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleActionGroup</doc> + <type name="SimpleActionGroup" c:type="GSimpleActionGroup*"/> + </instance-parameter> + <parameter name="action" transfer-ownership="none"> + <doc xml:space="preserve">a #GAction</doc> + <type name="Action" c:type="GAction*"/> + </parameter> + </parameters> + </method> + <method name="lookup" c:identifier="g_simple_action_group_lookup" version="2.28" deprecated="1" deprecated-version="2.38"> + <doc xml:space="preserve">Looks up the action with the name @action_name in the group. + +If no such action exists, returns %NULL.</doc> + <doc-deprecated xml:space="preserve">Use g_action_map_lookup_action()</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GAction, or %NULL</doc> + <type name="Action" c:type="GAction*"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleActionGroup</doc> + <type name="SimpleActionGroup" c:type="GSimpleActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of an action</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="remove" c:identifier="g_simple_action_group_remove" version="2.28" deprecated="1" deprecated-version="2.38"> + <doc xml:space="preserve">Removes the named action from the action group. + +If no action of this name is in the group then nothing happens.</doc> + <doc-deprecated xml:space="preserve">Use g_action_map_remove_action()</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleActionGroup</doc> + <type name="SimpleActionGroup" c:type="GSimpleActionGroup*"/> + </instance-parameter> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the action</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <field name="parent_instance" readable="0" private="1"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="SimpleActionGroupPrivate" c:type="GSimpleActionGroupPrivate*"/> + </field> + </class> + <record name="SimpleActionGroupClass" c:type="GSimpleActionGroupClass" glib:is-gtype-struct-for="SimpleActionGroup"> + <field name="parent_class" readable="0" private="1"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="12"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <record name="SimpleActionGroupPrivate" c:type="GSimpleActionGroupPrivate" disguised="1"/> + <class name="SimpleAsyncResult" c:symbol-prefix="simple_async_result" c:type="GSimpleAsyncResult" parent="GObject.Object" glib:type-name="GSimpleAsyncResult" glib:get-type="g_simple_async_result_get_type" glib:type-struct="SimpleAsyncResultClass"> + <doc xml:space="preserve">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); +} +]|</doc> + <implements name="AsyncResult"/> + <constructor name="new" c:identifier="g_simple_async_result_new" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_task_new() instead.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </return-value> + <parameters> + <parameter name="source_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GObject, or %NULL.</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="source_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the asynchronous function.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_error" c:identifier="g_simple_async_result_new_error" introspectable="0" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">Creates a new #GSimpleAsyncResult with a set error.</doc> + <doc-deprecated xml:space="preserve">Use g_task_new() and g_task_return_new_error() instead.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </return-value> + <parameters> + <parameter name="source_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GObject, or %NULL.</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="code" transfer-ownership="none"> + <doc xml:space="preserve">an error code.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a string with format characters.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">a list of values to insert into @format.</doc> + <varargs/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_error" c:identifier="g_simple_async_result_new_from_error" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">Creates a #GSimpleAsyncResult from an error condition.</doc> + <doc-deprecated xml:space="preserve">Use g_task_new() and g_task_return_error() instead.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </return-value> + <parameters> + <parameter name="source_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GObject, or %NULL.</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">a #GError</doc> + <type name="GLib.Error" c:type="const GError*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_take_error" c:identifier="g_simple_async_result_new_take_error" version="2.28" introspectable="0" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_task_new() and g_task_return_error() instead.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSimpleAsyncResult</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </return-value> + <parameters> + <parameter name="source_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GObject, or %NULL</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">a #GError</doc> + <type name="GLib.Error" c:type="GError*"/> + </parameter> + </parameters> + </constructor> + <function name="is_valid" c:identifier="g_simple_async_result_is_valid" version="2.20" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">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.)</doc> + <doc-deprecated xml:space="preserve">Use #GTask and g_task_is_valid() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">#TRUE if all checks passed or #FALSE if any failed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult passed to the _finish function.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="source" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the #GObject passed to the _finish function.</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + <parameter name="source_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the asynchronous function.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <method name="complete" c:identifier="g_simple_async_result_complete" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use #GTask instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + </parameters> + </method> + <method name="complete_in_idle" c:identifier="g_simple_async_result_complete_in_idle" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use #GTask instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_op_res_gboolean" c:identifier="g_simple_async_result_get_op_res_gboolean" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">Gets the operation result boolean from within the asynchronous result.</doc> + <doc-deprecated xml:space="preserve">Use #GTask and g_task_propagate_boolean() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation's result was %TRUE, %FALSE + if the operation's result was %FALSE.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_op_res_gpointer" c:identifier="g_simple_async_result_get_op_res_gpointer" introspectable="0" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">Gets a pointer result as returned by the asynchronous function.</doc> + <doc-deprecated xml:space="preserve">Use #GTask and g_task_propagate_pointer() instead.</doc-deprecated> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a pointer from the result.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_op_res_gssize" c:identifier="g_simple_async_result_get_op_res_gssize" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">Gets a gssize from the asynchronous result.</doc> + <doc-deprecated xml:space="preserve">Use #GTask and g_task_propagate_int() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a gssize returned from the asynchronous function.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_source_tag" c:identifier="g_simple_async_result_get_source_tag" introspectable="0" deprecated="1" deprecated-version="2.46."> + <doc xml:space="preserve">Gets the source tag for the #GSimpleAsyncResult.</doc> + <doc-deprecated xml:space="preserve">Use #GTask and g_task_get_source_tag() instead.</doc-deprecated> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a #gpointer to the source object for the #GSimpleAsyncResult.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + </parameters> + </method> + <method name="propagate_error" c:identifier="g_simple_async_result_propagate_error" deprecated="1" deprecated-version="2.46" throws="1"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use #GTask instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the error was propagated to @dest. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + </parameters> + </method> + <method name="run_in_thread" c:identifier="g_simple_async_result_run_in_thread" introspectable="0" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use #GTask and g_task_run_in_thread() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + <parameter name="func" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncThreadFunc.</doc> + <type name="SimpleAsyncThreadFunc" c:type="GSimpleAsyncThreadFunc"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the io priority of the request.</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_check_cancellable" c:identifier="g_simple_async_result_set_check_cancellable" version="2.32" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use #GTask instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + <parameter name="check_cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable to check, or %NULL to unset</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_error" c:identifier="g_simple_async_result_set_error" introspectable="0" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">Sets an error within the asynchronous result without a #GError.</doc> + <doc-deprecated xml:space="preserve">Use #GTask and g_task_return_new_error() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark (usually #G_IO_ERROR).</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="code" transfer-ownership="none"> + <doc xml:space="preserve">an error code.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a formatted error reporting string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">a list of variables to fill in @format.</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="set_error_va" c:identifier="g_simple_async_result_set_error_va" introspectable="0" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">Sets an error within the asynchronous result without a #GError. +Unless writing a binding, see g_simple_async_result_set_error().</doc> + <doc-deprecated xml:space="preserve">Use #GTask and g_task_return_error() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark (usually #G_IO_ERROR).</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="code" transfer-ownership="none"> + <doc xml:space="preserve">an error code.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a formatted error reporting string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="args" transfer-ownership="none"> + <doc xml:space="preserve">va_list of arguments.</doc> + <type name="va_list" c:type="va_list"/> + </parameter> + </parameters> + </method> + <method name="set_from_error" c:identifier="g_simple_async_result_set_from_error" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">Sets the result from a #GError.</doc> + <doc-deprecated xml:space="preserve">Use #GTask and g_task_return_error() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">#GError.</doc> + <type name="GLib.Error" c:type="const GError*"/> + </parameter> + </parameters> + </method> + <method name="set_handle_cancellation" c:identifier="g_simple_async_result_set_handle_cancellation" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + <parameter name="handle_cancellation" transfer-ownership="none"> + <doc xml:space="preserve">a #gboolean.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_op_res_gboolean" c:identifier="g_simple_async_result_set_op_res_gboolean" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">Sets the operation result to a boolean within the asynchronous result.</doc> + <doc-deprecated xml:space="preserve">Use #GTask and g_task_return_boolean() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + <parameter name="op_res" transfer-ownership="none"> + <doc xml:space="preserve">a #gboolean.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_op_res_gpointer" c:identifier="g_simple_async_result_set_op_res_gpointer" introspectable="0" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">Sets the operation result within the asynchronous result to a pointer.</doc> + <doc-deprecated xml:space="preserve">Use #GTask and g_task_return_pointer() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + <parameter name="op_res" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer result from an asynchronous function.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy_op_res" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">a #GDestroyNotify function.</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="set_op_res_gssize" c:identifier="g_simple_async_result_set_op_res_gssize" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">Sets the operation result within the asynchronous result to +the given @op_res.</doc> + <doc-deprecated xml:space="preserve">Use #GTask and g_task_return_int() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + <parameter name="op_res" transfer-ownership="none"> + <doc xml:space="preserve">a #gssize.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </method> + <method name="take_error" c:identifier="g_simple_async_result_take_error" version="2.28" introspectable="0" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use #GTask and g_task_return_error() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="simple" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </instance-parameter> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">a #GError</doc> + <type name="GLib.Error" c:type="GError*"/> + </parameter> + </parameters> + </method> + </class> + <record name="SimpleAsyncResultClass" c:type="GSimpleAsyncResultClass" disguised="1" glib:is-gtype-struct-for="SimpleAsyncResult"/> + <callback name="SimpleAsyncThreadFunc" c:type="GSimpleAsyncThreadFunc"> + <doc xml:space="preserve">Simple thread function that runs an asynchronous operation and +checks for cancellation.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleAsyncResult.</doc> + <type name="SimpleAsyncResult" c:type="GSimpleAsyncResult*"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve">a #GObject.</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + <class name="SimpleIOStream" c:symbol-prefix="simple_io_stream" c:type="GSimpleIOStream" version="2.44" parent="IOStream" glib:type-name="GSimpleIOStream" glib:get-type="g_simple_io_stream_get_type"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_simple_io_stream_new" version="2.44"> + <doc xml:space="preserve">Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream. +See also #GIOStream.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSimpleIOStream instance.</doc> + <type name="IOStream" c:type="GIOStream*"/> + </return-value> + <parameters> + <parameter name="input_stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream.</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="output_stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + </parameters> + </constructor> + <property name="input-stream" version="2.44" writable="1" construct-only="1" transfer-ownership="none"> + <type name="InputStream"/> + </property> + <property name="output-stream" version="2.44" writable="1" construct-only="1" transfer-ownership="none"> + <type name="OutputStream"/> + </property> + </class> + <class name="SimplePermission" c:symbol-prefix="simple_permission" c:type="GSimplePermission" parent="Permission" glib:type-name="GSimplePermission" glib:get-type="g_simple_permission_get_type"> + <doc xml:space="preserve">#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.</doc> + <constructor name="new" c:identifier="g_simple_permission_new" version="2.26"> + <doc xml:space="preserve">Creates a new #GPermission instance that represents an action that is +either always or never allowed.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the #GSimplePermission, as a #GPermission</doc> + <type name="Permission" c:type="GPermission*"/> + </return-value> + <parameters> + <parameter name="allowed" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the action is allowed</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </constructor> + </class> + <class name="SimpleProxyResolver" c:symbol-prefix="simple_proxy_resolver" c:type="GSimpleProxyResolver" version="2.36" parent="GObject.Object" glib:type-name="GSimpleProxyResolver" glib:get-type="g_simple_proxy_resolver_get_type" glib:type-struct="SimpleProxyResolverClass"> + <doc xml:space="preserve">#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().</doc> + <implements name="ProxyResolver"/> + <function name="new" c:identifier="g_simple_proxy_resolver_new" version="2.36"> + <doc xml:space="preserve">Creates a new #GSimpleProxyResolver. See +#GSimpleProxyResolver:default-proxy and +#GSimpleProxyResolver:ignore-hosts for more details on how the +arguments are interpreted.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSimpleProxyResolver</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </return-value> + <parameters> + <parameter name="default_proxy" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the default proxy to use, eg + "socks://192.168.1.1"</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="ignore_hosts" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional list of hosts/IP addresses + to not use a proxy for.</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </function> + <method name="set_default_proxy" c:identifier="g_simple_proxy_resolver_set_default_proxy" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleProxyResolver</doc> + <type name="SimpleProxyResolver" c:type="GSimpleProxyResolver*"/> + </instance-parameter> + <parameter name="default_proxy" transfer-ownership="none"> + <doc xml:space="preserve">the default proxy to use</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_ignore_hosts" c:identifier="g_simple_proxy_resolver_set_ignore_hosts" version="2.36"> + <doc xml:space="preserve">Sets the list of ignored hosts. + +See #GSimpleProxyResolver:ignore-hosts for more details on how the +@ignore_hosts argument is interpreted.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleProxyResolver</doc> + <type name="SimpleProxyResolver" c:type="GSimpleProxyResolver*"/> + </instance-parameter> + <parameter name="ignore_hosts" transfer-ownership="none"> + <doc xml:space="preserve">%NULL-terminated list of hosts/IP addresses + to not use a proxy for</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </method> + <method name="set_uri_proxy" c:identifier="g_simple_proxy_resolver_set_uri_proxy" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="resolver" transfer-ownership="none"> + <doc xml:space="preserve">a #GSimpleProxyResolver</doc> + <type name="SimpleProxyResolver" c:type="GSimpleProxyResolver*"/> + </instance-parameter> + <parameter name="uri_scheme" transfer-ownership="none"> + <doc xml:space="preserve">the URI scheme to add a proxy for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="proxy" transfer-ownership="none"> + <doc xml:space="preserve">the proxy to use for @uri_scheme</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <property name="default-proxy" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="ignore-hosts" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <array> + <type name="utf8"/> + </array> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="SimpleProxyResolverPrivate" c:type="GSimpleProxyResolverPrivate*"/> + </field> + </class> + <record name="SimpleProxyResolverClass" c:type="GSimpleProxyResolverClass" glib:is-gtype-struct-for="SimpleProxyResolver"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="SimpleProxyResolverPrivate" c:type="GSimpleProxyResolverPrivate" disguised="1"/> + <class name="Socket" c:symbol-prefix="socket" c:type="GSocket" version="2.22" parent="GObject.Object" glib:type-name="GSocket" glib:get-type="g_socket_get_type" glib:type-struct="SocketClass"> + <doc xml:space="preserve">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.</doc> + <implements name="DatagramBased"/> + <implements name="Initable"/> + <constructor name="new" c:identifier="g_socket_new" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocket or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="Socket" c:type="GSocket*"/> + </return-value> + <parameters> + <parameter name="family" transfer-ownership="none"> + <doc xml:space="preserve">the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4.</doc> + <type name="SocketFamily" c:type="GSocketFamily"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">the socket type to use.</doc> + <type name="SocketType" c:type="GSocketType"/> + </parameter> + <parameter name="protocol" transfer-ownership="none"> + <doc xml:space="preserve">the id of the protocol to use, or 0 for default.</doc> + <type name="SocketProtocol" c:type="GSocketProtocol"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_fd" c:identifier="g_socket_new_from_fd" version="2.22" throws="1"> + <doc xml:space="preserve">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</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocket or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="Socket" c:type="GSocket*"/> + </return-value> + <parameters> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a native socket file descriptor.</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </constructor> + <method name="accept" c:identifier="g_socket_accept" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSocket, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="Socket" c:type="GSocket*"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="bind" c:identifier="g_socket_bind" version="2.22" throws="1"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddress specifying the local address.</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </parameter> + <parameter name="allow_reuse" transfer-ownership="none"> + <doc xml:space="preserve">whether to allow reusing this address</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="check_connect_result" c:identifier="g_socket_check_connect_result" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if no error, %FALSE otherwise, setting @error to the error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="close" c:identifier="g_socket_close" version="2.22" throws="1"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="condition_check" c:identifier="g_socket_condition_check" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the @GIOCondition mask of the current state</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOCondition mask to check</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </parameter> + </parameters> + </method> + <method name="condition_timed_wait" c:identifier="g_socket_condition_timed_wait" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the condition was met, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOCondition mask to wait for</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="timeout_us" transfer-ownership="none"> + <doc xml:space="preserve">the maximum time (in microseconds) to wait, or -1</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="condition_wait" c:identifier="g_socket_condition_wait" version="2.22" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the condition was met, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOCondition mask to wait for</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="connect" c:identifier="g_socket_connect" version="2.22" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if connected, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddress specifying the remote address.</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="connection_factory_create_connection" c:identifier="g_socket_connection_factory_create_connection" version="2.22"> + <doc xml:space="preserve">Creates a #GSocketConnection subclass of the right type for +@socket.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketConnection</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="create_source" c:identifier="g_socket_create_source" version="2.22" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated %GSource, free with g_source_unref().</doc> + <type name="GLib.Source" c:type="GSource*"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">a #GIOCondition mask to monitor</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="get_available_bytes" c:identifier="g_socket_get_available_bytes" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes that can be read from the socket +without blocking or truncating, or -1 on error.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_blocking" c:identifier="g_socket_get_blocking" version="2.22"> + <doc xml:space="preserve">Gets the blocking mode of the socket. For details on blocking I/O, +see g_socket_set_blocking().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if blocking I/O is used, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_broadcast" c:identifier="g_socket_get_broadcast" version="2.32"> + <doc xml:space="preserve">Gets the broadcast setting on @socket; if %TRUE, +it is possible to send packets to broadcast +addresses.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the broadcast setting on @socket</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_credentials" c:identifier="g_socket_get_credentials" version="2.26" throws="1"> + <doc xml:space="preserve">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 +- macOS, tvOS, iOS since GLib 2.66 + +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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">%NULL if @error is set, otherwise a #GCredentials object +that must be freed with g_object_unref().</doc> + <type name="Credentials" c:type="GCredentials*"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_family" c:identifier="g_socket_get_family" version="2.22"> + <doc xml:space="preserve">Gets the socket family of the socket.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketFamily</doc> + <type name="SocketFamily" c:type="GSocketFamily"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_fd" c:identifier="g_socket_get_fd" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the file descriptor of the socket.</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_keepalive" c:identifier="g_socket_get_keepalive" version="2.22"> + <doc xml:space="preserve">Gets the keepalive mode of the socket. For details on this, +see g_socket_set_keepalive().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if keepalive is active, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_listen_backlog" c:identifier="g_socket_get_listen_backlog" version="2.22"> + <doc xml:space="preserve">Gets the listen backlog setting of the socket. For details on this, +see g_socket_set_listen_backlog().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the maximum number of pending connections.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_local_address" c:identifier="g_socket_get_local_address" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketAddress or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_multicast_loopback" c:identifier="g_socket_get_multicast_loopback" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the multicast loopback setting on @socket</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_multicast_ttl" c:identifier="g_socket_get_multicast_ttl" version="2.32"> + <doc xml:space="preserve">Gets the multicast time-to-live setting on @socket; see +g_socket_set_multicast_ttl() for more details.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the multicast time-to-live setting on @socket</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_option" c:identifier="g_socket_get_option" version="2.36" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="level" transfer-ownership="none"> + <doc xml:space="preserve">the "API level" of the option (eg, `SOL_SOCKET`)</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="optname" transfer-ownership="none"> + <doc xml:space="preserve">the "name" of the option (eg, `SO_BROADCAST`)</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">return location for the option value</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </method> + <method name="get_protocol" c:identifier="g_socket_get_protocol" version="2.22"> + <doc xml:space="preserve">Gets the socket protocol id the socket was created with. +In case the protocol is unknown, -1 is returned.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a protocol id, or -1 if unknown</doc> + <type name="SocketProtocol" c:type="GSocketProtocol"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_remote_address" c:identifier="g_socket_get_remote_address" version="2.22" throws="1"> + <doc xml:space="preserve">Try to get the remote address of a connected socket. This is only +useful for connection oriented sockets that have been connected.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketAddress or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_socket_type" c:identifier="g_socket_get_socket_type" version="2.22"> + <doc xml:space="preserve">Gets the socket type of the socket.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketType</doc> + <type name="SocketType" c:type="GSocketType"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_timeout" c:identifier="g_socket_get_timeout" version="2.26"> + <doc xml:space="preserve">Gets the timeout setting of the socket. For details on this, see +g_socket_set_timeout().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the timeout in seconds</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_ttl" c:identifier="g_socket_get_ttl" version="2.32"> + <doc xml:space="preserve">Gets the unicast time-to-live setting on @socket; see +g_socket_set_ttl() for more details.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the time-to-live setting on @socket</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_closed" c:identifier="g_socket_is_closed" version="2.22"> + <doc xml:space="preserve">Checks whether a socket is closed.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if socket is closed, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_connected" c:identifier="g_socket_is_connected" version="2.22"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if socket is connected, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="join_multicast_group" c:identifier="g_socket_join_multicast_group" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress specifying the group address to join.</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + <parameter name="source_specific" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if source-specific multicast should be used</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="iface" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Name of the interface to use, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="join_multicast_group_ssm" c:identifier="g_socket_join_multicast_group_ssm" version="2.56" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress specifying the group address to join.</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + <parameter name="source_specific" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GInetAddress specifying the +source-specific multicast address or %NULL to ignore.</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + <parameter name="iface" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Name of the interface to use, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="leave_multicast_group" c:identifier="g_socket_leave_multicast_group" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress specifying the group address to leave.</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + <parameter name="source_specific" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if source-specific multicast was used</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="iface" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Interface used</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="leave_multicast_group_ssm" c:identifier="g_socket_leave_multicast_group_ssm" version="2.56" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="group" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetAddress specifying the group address to leave.</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + <parameter name="source_specific" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GInetAddress specifying the +source-specific multicast address or %NULL to ignore.</doc> + <type name="InetAddress" c:type="GInetAddress*"/> + </parameter> + <parameter name="iface" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Name of the interface to use, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="listen" c:identifier="g_socket_listen" version="2.22" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <method name="receive" c:identifier="g_socket_receive" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of bytes read, or 0 if the connection was closed by +the peer, or -1 on error</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="buffer" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve"> + a buffer to read data into (which should be at least @size bytes long).</doc> + <array length="1" zero-terminated="0" c:type="gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="size" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the number of bytes you want to read from the socket</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="receive_from" c:identifier="g_socket_receive_from" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of bytes read, or 0 if the connection was closed by +the peer, or -1 on error</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="address" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a pointer to a #GSocketAddress + pointer, or %NULL</doc> + <type name="SocketAddress" c:type="GSocketAddress**"/> + </parameter> + <parameter name="buffer" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve"> + a buffer to read data into (which should be at least @size bytes long).</doc> + <array length="2" zero-terminated="0" c:type="gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="size" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the number of bytes you want to read from the socket</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="receive_message" c:identifier="g_socket_receive_message" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of bytes read, or 0 if the connection was closed by +the peer, or -1 on error</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="address" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a pointer to a #GSocketAddress + pointer, or %NULL</doc> + <type name="SocketAddress" c:type="GSocketAddress**"/> + </parameter> + <parameter name="vectors" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GInputVector structs</doc> + <array length="2" zero-terminated="0" c:type="GInputVector*"> + <type name="InputVector" c:type="GInputVector"/> + </array> + </parameter> + <parameter name="num_vectors" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements in @vectors, or -1</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="messages" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">a pointer + which may be filled with an array of #GSocketControlMessages, or %NULL</doc> + <array length="4" zero-terminated="0" c:type="GSocketControlMessage***"> + <type name="SocketControlMessage" c:type="GSocketControlMessage**"/> + </array> + </parameter> + <parameter name="num_messages" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">a pointer which will be filled with the number of + elements in @messages, or %NULL</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="flags" direction="inout" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">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)</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="receive_messages" c:identifier="g_socket_receive_messages" version="2.48" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="messages" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GInputMessage structs</doc> + <array length="1" zero-terminated="0" c:type="GInputMessage*"> + <type name="InputMessage" c:type="GInputMessage"/> + </array> + </parameter> + <parameter name="num_messages" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements in @messages</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">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)</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="receive_with_blocking" c:identifier="g_socket_receive_with_blocking" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of bytes read, or 0 if the connection was closed by +the peer, or -1 on error</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="buffer" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve"> + a buffer to read data into (which should be at least @size bytes long).</doc> + <array length="1" zero-terminated="0" c:type="gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="size" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the number of bytes you want to read from the socket</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="blocking" transfer-ownership="none"> + <doc xml:space="preserve">whether to do blocking or non-blocking I/O</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="send" c:identifier="g_socket_send" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of bytes written (which may be less than @size), or -1 +on error</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">the buffer + containing the data to send.</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to send</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="send_message" c:identifier="g_socket_send_message" version="2.22" throws="1"> + <doc xml:space="preserve">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.) + +The sum of the sizes of each #GOutputVector in vectors must not be +greater than %G_MAXSSIZE. If the message can be larger than this, +then it is mandatory to use the g_socket_send_message_with_timeout() +function. + +On error -1 is returned and @error is set accordingly.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of bytes written (which may be less than @size), or -1 +on error</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="address" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GSocketAddress, or %NULL</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </parameter> + <parameter name="vectors" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GOutputVector structs</doc> + <array length="2" zero-terminated="0" c:type="GOutputVector*"> + <type name="OutputVector" c:type="GOutputVector"/> + </array> + </parameter> + <parameter name="num_vectors" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements in @vectors, or -1</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="messages" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to an + array of #GSocketControlMessages, or %NULL.</doc> + <array length="4" zero-terminated="0" c:type="GSocketControlMessage**"> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </array> + </parameter> + <parameter name="num_messages" transfer-ownership="none"> + <doc xml:space="preserve">number of elements in @messages, or -1.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">an int containing #GSocketMsgFlags flags, which may additionally + contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="send_message_with_timeout" c:identifier="g_socket_send_message_with_timeout" version="2.60" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%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.</doc> + <type name="PollableReturn" c:type="GPollableReturn"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="address" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GSocketAddress, or %NULL</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </parameter> + <parameter name="vectors" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GOutputVector structs</doc> + <array length="2" zero-terminated="0" c:type="const GOutputVector*"> + <type name="OutputVector" c:type="GOutputVector"/> + </array> + </parameter> + <parameter name="num_vectors" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements in @vectors, or -1</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="messages" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to an + array of #GSocketControlMessages, or %NULL.</doc> + <array length="4" zero-terminated="0" c:type="GSocketControlMessage**"> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </array> + </parameter> + <parameter name="num_messages" transfer-ownership="none"> + <doc xml:space="preserve">number of elements in @messages, or -1.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">an int containing #GSocketMsgFlags flags, which may additionally + contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="timeout_us" transfer-ownership="none"> + <doc xml:space="preserve">the maximum time (in microseconds) to wait, or -1</doc> + <type name="gint64" c:type="gint64"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the number of bytes that were written to the socket</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="send_messages" c:identifier="g_socket_send_messages" version="2.44" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="messages" transfer-ownership="none"> + <doc xml:space="preserve">an array of #GOutputMessage structs</doc> + <array length="1" zero-terminated="0" c:type="GOutputMessage*"> + <type name="OutputMessage" c:type="GOutputMessage"/> + </array> + </parameter> + <parameter name="num_messages" transfer-ownership="none"> + <doc xml:space="preserve">the number of elements in @messages</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">an int containing #GSocketMsgFlags flags, which may additionally + contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="send_to" c:identifier="g_socket_send_to" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of bytes written (which may be less than @size), or -1 +on error</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="address" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GSocketAddress, or %NULL</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </parameter> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">the buffer + containing the data to send.</doc> + <array length="2" zero-terminated="0" c:type="const gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to send</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="send_with_blocking" c:identifier="g_socket_send_with_blocking" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">Number of bytes written (which may be less than @size), or -1 +on error</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">the buffer + containing the data to send.</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to send</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="blocking" transfer-ownership="none"> + <doc xml:space="preserve">whether to do blocking or non-blocking I/O</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_blocking" c:identifier="g_socket_set_blocking" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="blocking" transfer-ownership="none"> + <doc xml:space="preserve">Whether to use blocking I/O or not.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_broadcast" c:identifier="g_socket_set_broadcast" version="2.32"> + <doc xml:space="preserve">Sets whether @socket should allow sending to broadcast addresses. +This is %FALSE by default.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="broadcast" transfer-ownership="none"> + <doc xml:space="preserve">whether @socket should allow sending to broadcast + addresses</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_keepalive" c:identifier="g_socket_set_keepalive" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="keepalive" transfer-ownership="none"> + <doc xml:space="preserve">Value for the keepalive flag</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_listen_backlog" c:identifier="g_socket_set_listen_backlog" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="backlog" transfer-ownership="none"> + <doc xml:space="preserve">the maximum number of pending connections.</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="set_multicast_loopback" c:identifier="g_socket_set_multicast_loopback" version="2.32"> + <doc xml:space="preserve">Sets whether outgoing multicast packets will be received by sockets +listening on that multicast address on the same host. This is %TRUE +by default.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="loopback" transfer-ownership="none"> + <doc xml:space="preserve">whether @socket should receive messages sent to its + multicast groups from the local host</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_multicast_ttl" c:identifier="g_socket_set_multicast_ttl" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="ttl" transfer-ownership="none"> + <doc xml:space="preserve">the time-to-live value for all multicast datagrams on @socket</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="set_option" c:identifier="g_socket_set_option" version="2.36" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="level" transfer-ownership="none"> + <doc xml:space="preserve">the "API level" of the option (eg, `SOL_SOCKET`)</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="optname" transfer-ownership="none"> + <doc xml:space="preserve">the "name" of the option (eg, `SO_BROADCAST`)</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value to set the option to</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="set_timeout" c:identifier="g_socket_set_timeout" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="timeout" transfer-ownership="none"> + <doc xml:space="preserve">the timeout for @socket, in seconds, or 0 for none</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="set_ttl" c:identifier="g_socket_set_ttl" version="2.32"> + <doc xml:space="preserve">Sets the time-to-live for outgoing unicast packets on @socket. +By default the platform-specific default value is used.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket.</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="ttl" transfer-ownership="none"> + <doc xml:space="preserve">the time-to-live value for all unicast packets on @socket</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="shutdown" c:identifier="g_socket_shutdown" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + <parameter name="shutdown_read" transfer-ownership="none"> + <doc xml:space="preserve">whether to shut down the read side</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="shutdown_write" transfer-ownership="none"> + <doc xml:space="preserve">whether to shut down the write side</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="speaks_ipv4" c:identifier="g_socket_speaks_ipv4" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if this socket can be used with IPv4.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </instance-parameter> + </parameters> + </method> + <property name="blocking" writable="1" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="broadcast" version="2.32" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">Whether the socket should allow sending to broadcast addresses.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="family" writable="1" construct-only="1" transfer-ownership="none"> + <type name="SocketFamily"/> + </property> + <property name="fd" writable="1" construct-only="1" transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </property> + <property name="keepalive" writable="1" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="listen-backlog" writable="1" transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </property> + <property name="local-address" transfer-ownership="none"> + <type name="SocketAddress"/> + </property> + <property name="multicast-loopback" version="2.32" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">Whether outgoing multicast packets loop back to the local host.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="multicast-ttl" version="2.32" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">Time-to-live out outgoing multicast packets</doc> + <type name="guint" c:type="guint"/> + </property> + <property name="protocol" writable="1" construct-only="1" transfer-ownership="none"> + <type name="SocketProtocol"/> + </property> + <property name="remote-address" transfer-ownership="none"> + <type name="SocketAddress"/> + </property> + <property name="timeout" version="2.26" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">The timeout in seconds on socket I/O</doc> + <type name="guint" c:type="guint"/> + </property> + <property name="ttl" version="2.32" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">Time-to-live for outgoing unicast packets</doc> + <type name="guint" c:type="guint"/> + </property> + <property name="type" writable="1" construct-only="1" transfer-ownership="none"> + <type name="SocketType"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv"> + <type name="SocketPrivate" c:type="GSocketPrivate*"/> + </field> + </class> + <class name="SocketAddress" c:symbol-prefix="socket_address" c:type="GSocketAddress" parent="GObject.Object" abstract="1" glib:type-name="GSocketAddress" glib:get-type="g_socket_address_get_type" glib:type-struct="SocketAddressClass"> + <doc xml:space="preserve">#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.</doc> + <implements name="SocketConnectable"/> + <constructor name="new_from_native" c:identifier="g_socket_address_new_from_native" version="2.22"> + <doc xml:space="preserve">Creates a #GSocketAddress subclass corresponding to the native +struct sockaddr @native.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSocketAddress if @native could successfully + be converted, otherwise %NULL</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <parameter name="native" transfer-ownership="none"> + <doc xml:space="preserve">a pointer to a struct sockaddr</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the size of the memory location pointed to by @native</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </constructor> + <virtual-method name="get_family" invoker="get_family" version="2.22"> + <doc xml:space="preserve">Gets the socket family type of @address.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the socket family type of @address</doc> + <type name="SocketFamily" c:type="GSocketFamily"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddress</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_native_size" invoker="get_native_size" version="2.22"> + <doc xml:space="preserve">Gets the size of @address's native struct sockaddr. +You can use this to allocate memory to pass to +g_socket_address_to_native().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the size of the native struct sockaddr that + @address represents</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddress</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="to_native" invoker="to_native" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @dest was filled in, %FALSE on error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddress</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </instance-parameter> + <parameter name="dest" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to a memory location that will contain the native +struct sockaddr</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destlen" transfer-ownership="none"> + <doc xml:space="preserve">the size of @dest. Must be at least as large as + g_socket_address_get_native_size()</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_family" c:identifier="g_socket_address_get_family" version="2.22"> + <doc xml:space="preserve">Gets the socket family type of @address.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the socket family type of @address</doc> + <type name="SocketFamily" c:type="GSocketFamily"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddress</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_native_size" c:identifier="g_socket_address_get_native_size" version="2.22"> + <doc xml:space="preserve">Gets the size of @address's native struct sockaddr. +You can use this to allocate memory to pass to +g_socket_address_to_native().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the size of the native struct sockaddr that + @address represents</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddress</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="to_native" c:identifier="g_socket_address_to_native" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @dest was filled in, %FALSE on error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddress</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </instance-parameter> + <parameter name="dest" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to a memory location that will contain the native +struct sockaddr</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destlen" transfer-ownership="none"> + <doc xml:space="preserve">the size of @dest. Must be at least as large as + g_socket_address_get_native_size()</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </method> + <property name="family" transfer-ownership="none"> + <type name="SocketFamily"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + </class> + <record name="SocketAddressClass" c:type="GSocketAddressClass" glib:is-gtype-struct-for="SocketAddress"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="get_family"> + <callback name="get_family"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the socket family type of @address</doc> + <type name="SocketFamily" c:type="GSocketFamily"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddress</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_native_size"> + <callback name="get_native_size"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the size of the native struct sockaddr that + @address represents</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddress</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="to_native"> + <callback name="to_native" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @dest was filled in, %FALSE on error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddress</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </parameter> + <parameter name="dest" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a pointer to a memory location that will contain the native +struct sockaddr</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destlen" transfer-ownership="none"> + <doc xml:space="preserve">the size of @dest. Must be at least as large as + g_socket_address_get_native_size()</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="SocketAddressEnumerator" c:symbol-prefix="socket_address_enumerator" c:type="GSocketAddressEnumerator" parent="GObject.Object" abstract="1" glib:type-name="GSocketAddressEnumerator" glib:get-type="g_socket_address_enumerator_get_type" glib:type-struct="SocketAddressEnumeratorClass"> + <doc xml:space="preserve">#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, further +enumeration with that #GSocketAddressEnumerator is not possible, and it can +be unreffed.</doc> + <virtual-method name="next" invoker="next" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketAddress (owned by the caller), or %NULL on + error (in which case *@error will be set) or if there are no + more addresses.</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddressEnumerator</doc> + <type name="SocketAddressEnumerator" c:type="GSocketAddressEnumerator*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="next_async" invoker="next_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddressEnumerator</doc> + <type name="SocketAddressEnumerator" c:type="GSocketAddressEnumerator*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request + is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="next_finish" invoker="next_finish" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketAddress (owned by the caller), or %NULL on + error (in which case *@error will be set) or if there are no + more addresses.</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddressEnumerator</doc> + <type name="SocketAddressEnumerator" c:type="GSocketAddressEnumerator*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <method name="next" c:identifier="g_socket_address_enumerator_next" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketAddress (owned by the caller), or %NULL on + error (in which case *@error will be set) or if there are no + more addresses.</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddressEnumerator</doc> + <type name="SocketAddressEnumerator" c:type="GSocketAddressEnumerator*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="next_async" c:identifier="g_socket_address_enumerator_next_async"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddressEnumerator</doc> + <type name="SocketAddressEnumerator" c:type="GSocketAddressEnumerator*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request + is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="next_finish" c:identifier="g_socket_address_enumerator_next_finish" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketAddress (owned by the caller), or %NULL on + error (in which case *@error will be set) or if there are no + more addresses.</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <instance-parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddressEnumerator</doc> + <type name="SocketAddressEnumerator" c:type="GSocketAddressEnumerator*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <field name="parent_instance" readable="0" private="1"> + <type name="GObject.Object" c:type="GObject"/> + </field> + </class> + <record name="SocketAddressEnumeratorClass" c:type="GSocketAddressEnumeratorClass" glib:is-gtype-struct-for="SocketAddressEnumerator"> + <doc xml:space="preserve">Class structure for #GSocketAddressEnumerator.</doc> + <field name="parent_class" readable="0" private="1"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="next"> + <callback name="next" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketAddress (owned by the caller), or %NULL on + error (in which case *@error will be set) or if there are no + more addresses.</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddressEnumerator</doc> + <type name="SocketAddressEnumerator" c:type="GSocketAddressEnumerator*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="next_async"> + <callback name="next_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddressEnumerator</doc> + <type name="SocketAddressEnumerator" c:type="GSocketAddressEnumerator*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request + is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="next_finish"> + <callback name="next_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketAddress (owned by the caller), or %NULL on + error (in which case *@error will be set) or if there are no + more addresses.</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <parameter name="enumerator" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddressEnumerator</doc> + <type name="SocketAddressEnumerator" c:type="GSocketAddressEnumerator*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <record name="SocketClass" c:type="GSocketClass" glib:is-gtype-struct-for="Socket"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved6" introspectable="0"> + <callback name="_g_reserved6"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved7" introspectable="0"> + <callback name="_g_reserved7"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved8" introspectable="0"> + <callback name="_g_reserved8"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved9" introspectable="0"> + <callback name="_g_reserved9"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved10" introspectable="0"> + <callback name="_g_reserved10"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <class name="SocketClient" c:symbol-prefix="socket_client" c:type="GSocketClient" version="2.22" parent="GObject.Object" glib:type-name="GSocketClient" glib:get-type="g_socket_client_get_type" glib:type-struct="SocketClientClass"> + <doc xml:space="preserve">#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.</doc> + <constructor name="new" c:identifier="g_socket_client_new" version="2.22"> + <doc xml:space="preserve">Creates a new #GSocketClient with the default options.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketClient. + Free the returned object with g_object_unref().</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </return-value> + </constructor> + <virtual-method name="event"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="event" transfer-ownership="none"> + <type name="SocketClientEvent" c:type="GSocketClientEvent"/> + </parameter> + <parameter name="connectable" transfer-ownership="none"> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="connection" transfer-ownership="none"> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + </parameters> + </virtual-method> + <method name="add_application_proxy" c:identifier="g_socket_client_add_application_proxy"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="protocol" transfer-ownership="none"> + <doc xml:space="preserve">The proxy protocol</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="connect" c:identifier="g_socket_client_connect" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketConnection on success, %NULL on error.</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable specifying the remote address.</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="connect_async" c:identifier="g_socket_client_connect_async" version="2.22"> + <doc xml:space="preserve">This is the asynchronous version of g_socket_client_connect(). + +You may wish to prefer the asynchronous version even in synchronous +command line programs because, since 2.60, it implements +[RFC 8305](https://tools.ietf.org/html/rfc8305) "Happy Eyeballs" +recommendations to work around long connection timeouts in networks +where IPv6 is broken by performing an IPv4 connection simultaneously +without waiting for IPv6 to time out, which is not supported by the +synchronous call. (This is not an API guarantee, and may change in +the future.) + +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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable specifying the remote address.</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data for the callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="connect_finish" c:identifier="g_socket_client_connect_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an async connect operation. See g_socket_client_connect_async()</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketConnection on success, %NULL on error.</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="connect_to_host" c:identifier="g_socket_client_connect_to_host" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketConnection on success, %NULL on error.</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="host_and_port" transfer-ownership="none"> + <doc xml:space="preserve">the name and optionally port of the host to connect to</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="default_port" transfer-ownership="none"> + <doc xml:space="preserve">the default port to connect to</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="connect_to_host_async" c:identifier="g_socket_client_connect_to_host_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="host_and_port" transfer-ownership="none"> + <doc xml:space="preserve">the name and optionally the port of the host to connect to</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="default_port" transfer-ownership="none"> + <doc xml:space="preserve">the default port to connect to</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data for the callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="connect_to_host_finish" c:identifier="g_socket_client_connect_to_host_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an async connect operation. See g_socket_client_connect_to_host_async()</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketConnection on success, %NULL on error.</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="connect_to_service" c:identifier="g_socket_client_connect_to_service" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketConnection if successful, or %NULL on error</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnection</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">a domain name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="service" transfer-ownership="none"> + <doc xml:space="preserve">the name of the service to connect to</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="connect_to_service_async" c:identifier="g_socket_client_connect_to_service_async" version="2.22"> + <doc xml:space="preserve">This is the asynchronous version of +g_socket_client_connect_to_service().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">a domain name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="service" transfer-ownership="none"> + <doc xml:space="preserve">the name of the service to connect to</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data for the callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="connect_to_service_finish" c:identifier="g_socket_client_connect_to_service_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an async connect operation. See g_socket_client_connect_to_service_async()</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketConnection on success, %NULL on error.</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="connect_to_uri" c:identifier="g_socket_client_connect_to_uri" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketConnection on success, %NULL on error.</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">A network URI</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="default_port" transfer-ownership="none"> + <doc xml:space="preserve">the default port to connect to</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="connect_to_uri_async" c:identifier="g_socket_client_connect_to_uri_async" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a network uri</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="default_port" transfer-ownership="none"> + <doc xml:space="preserve">the default port to connect to</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data for the callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="connect_to_uri_finish" c:identifier="g_socket_client_connect_to_uri_finish" version="2.26" throws="1"> + <doc xml:space="preserve">Finishes an async connect operation. See g_socket_client_connect_to_uri_async()</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketConnection on success, %NULL on error.</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="get_enable_proxy" c:identifier="g_socket_client_get_enable_proxy" version="2.26"> + <doc xml:space="preserve">Gets the proxy enable state; see g_socket_client_set_enable_proxy()</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether proxying is enabled</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_family" c:identifier="g_socket_client_get_family" version="2.22"> + <doc xml:space="preserve">Gets the socket family of the socket client. + +See g_socket_client_set_family() for details.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketFamily</doc> + <type name="SocketFamily" c:type="GSocketFamily"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_local_address" c:identifier="g_socket_client_get_local_address" version="2.22"> + <doc xml:space="preserve">Gets the local address of the socket client. + +See g_socket_client_set_local_address() for details.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a #GSocketAddress or %NULL. Do not free.</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_protocol" c:identifier="g_socket_client_get_protocol" version="2.22"> + <doc xml:space="preserve">Gets the protocol name type of the socket client. + +See g_socket_client_set_protocol() for details.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketProtocol</doc> + <type name="SocketProtocol" c:type="GSocketProtocol"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_proxy_resolver" c:identifier="g_socket_client_get_proxy_resolver" version="2.36"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The #GProxyResolver being used by + @client.</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_socket_type" c:identifier="g_socket_client_get_socket_type" version="2.22"> + <doc xml:space="preserve">Gets the socket type of the socket client. + +See g_socket_client_set_socket_type() for details.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketFamily</doc> + <type name="SocketType" c:type="GSocketType"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_timeout" c:identifier="g_socket_client_get_timeout" version="2.26"> + <doc xml:space="preserve">Gets the I/O timeout time for sockets created by @client. + +See g_socket_client_set_timeout() for details.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the timeout in seconds</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_tls" c:identifier="g_socket_client_get_tls" version="2.28"> + <doc xml:space="preserve">Gets whether @client creates TLS connections. See +g_socket_client_set_tls() for details.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether @client uses TLS</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_tls_validation_flags" c:identifier="g_socket_client_get_tls_validation_flags" version="2.28"> + <doc xml:space="preserve">Gets the TLS validation flags used creating TLS connections via +@client.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the TLS validation flags</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_enable_proxy" c:identifier="g_socket_client_set_enable_proxy" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="enable" transfer-ownership="none"> + <doc xml:space="preserve">whether to enable proxies</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_family" c:identifier="g_socket_client_set_family" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="family" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketFamily</doc> + <type name="SocketFamily" c:type="GSocketFamily"/> + </parameter> + </parameters> + </method> + <method name="set_local_address" c:identifier="g_socket_client_set_local_address" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="address" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GSocketAddress, or %NULL</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </parameter> + </parameters> + </method> + <method name="set_protocol" c:identifier="g_socket_client_set_protocol" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="protocol" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketProtocol</doc> + <type name="SocketProtocol" c:type="GSocketProtocol"/> + </parameter> + </parameters> + </method> + <method name="set_proxy_resolver" c:identifier="g_socket_client_set_proxy_resolver" version="2.36"> + <doc xml:space="preserve">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)</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="proxy_resolver" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GProxyResolver, or %NULL for the + default.</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </parameter> + </parameters> + </method> + <method name="set_socket_type" c:identifier="g_socket_client_set_socket_type" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketType</doc> + <type name="SocketType" c:type="GSocketType"/> + </parameter> + </parameters> + </method> + <method name="set_timeout" c:identifier="g_socket_client_set_timeout" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="timeout" transfer-ownership="none"> + <doc xml:space="preserve">the timeout</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="set_tls" c:identifier="g_socket_client_set_tls" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="tls" transfer-ownership="none"> + <doc xml:space="preserve">whether to use TLS</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_tls_validation_flags" c:identifier="g_socket_client_set_tls_validation_flags" version="2.28"> + <doc xml:space="preserve">Sets the TLS validation flags used when creating TLS connections +via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="client" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketClient.</doc> + <type name="SocketClient" c:type="GSocketClient*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">the validation flags</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </parameter> + </parameters> + </method> + <property name="enable-proxy" writable="1" construct="1" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="family" writable="1" construct="1" transfer-ownership="none"> + <type name="SocketFamily"/> + </property> + <property name="local-address" writable="1" construct="1" transfer-ownership="none"> + <type name="SocketAddress"/> + </property> + <property name="protocol" writable="1" construct="1" transfer-ownership="none"> + <type name="SocketProtocol"/> + </property> + <property name="proxy-resolver" version="2.36" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">The proxy resolver to use</doc> + <type name="ProxyResolver"/> + </property> + <property name="timeout" writable="1" construct="1" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </property> + <property name="tls" writable="1" construct="1" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="tls-validation-flags" writable="1" construct="1" transfer-ownership="none"> + <type name="TlsCertificateFlags"/> + </property> + <property name="type" writable="1" construct="1" transfer-ownership="none"> + <type name="SocketType"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv"> + <type name="SocketClientPrivate" c:type="GSocketClientPrivate*"/> + </field> + <glib:signal name="event" when="last" version="2.32"> + <doc xml:space="preserve">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, then 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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="event" transfer-ownership="none"> + <doc xml:space="preserve">the event that is occurring</doc> + <type name="SocketClientEvent"/> + </parameter> + <parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">the #GSocketConnectable that @event is occurring on</doc> + <type name="SocketConnectable"/> + </parameter> + <parameter name="connection" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the current representation of the connection</doc> + <type name="IOStream"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="SocketClientClass" c:type="GSocketClientClass" glib:is-gtype-struct-for="SocketClient"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="event"> + <callback name="event"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="client" transfer-ownership="none"> + <type name="SocketClient" c:type="GSocketClient*"/> + </parameter> + <parameter name="event" transfer-ownership="none"> + <type name="SocketClientEvent" c:type="GSocketClientEvent"/> + </parameter> + <parameter name="connectable" transfer-ownership="none"> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="connection" transfer-ownership="none"> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <enumeration name="SocketClientEvent" version="2.32" glib:type-name="GSocketClientEvent" glib:get-type="g_socket_client_event_get_type" c:type="GSocketClientEvent"> + <doc xml:space="preserve">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.</doc> + <member name="resolving" value="0" c:identifier="G_SOCKET_CLIENT_RESOLVING" glib:nick="resolving"> + <doc xml:space="preserve">The client is doing a DNS lookup.</doc> + </member> + <member name="resolved" value="1" c:identifier="G_SOCKET_CLIENT_RESOLVED" glib:nick="resolved"> + <doc xml:space="preserve">The client has completed a DNS lookup.</doc> + </member> + <member name="connecting" value="2" c:identifier="G_SOCKET_CLIENT_CONNECTING" glib:nick="connecting"> + <doc xml:space="preserve">The client is connecting to a remote + host (either a proxy or the destination server).</doc> + </member> + <member name="connected" value="3" c:identifier="G_SOCKET_CLIENT_CONNECTED" glib:nick="connected"> + <doc xml:space="preserve">The client has connected to a remote + host.</doc> + </member> + <member name="proxy_negotiating" value="4" c:identifier="G_SOCKET_CLIENT_PROXY_NEGOTIATING" glib:nick="proxy-negotiating"> + <doc xml:space="preserve">The client is negotiating + with a proxy to connect to the destination server.</doc> + </member> + <member name="proxy_negotiated" value="5" c:identifier="G_SOCKET_CLIENT_PROXY_NEGOTIATED" glib:nick="proxy-negotiated"> + <doc xml:space="preserve">The client has negotiated + with the proxy server.</doc> + </member> + <member name="tls_handshaking" value="6" c:identifier="G_SOCKET_CLIENT_TLS_HANDSHAKING" glib:nick="tls-handshaking"> + <doc xml:space="preserve">The client is performing a + TLS handshake.</doc> + </member> + <member name="tls_handshaked" value="7" c:identifier="G_SOCKET_CLIENT_TLS_HANDSHAKED" glib:nick="tls-handshaked"> + <doc xml:space="preserve">The client has performed a + TLS handshake.</doc> + </member> + <member name="complete" value="8" c:identifier="G_SOCKET_CLIENT_COMPLETE" glib:nick="complete"> + <doc xml:space="preserve">The client is done with a particular + #GSocketConnectable.</doc> + </member> + </enumeration> + <record name="SocketClientPrivate" c:type="GSocketClientPrivate" disguised="1"/> + <interface name="SocketConnectable" c:symbol-prefix="socket_connectable" c:type="GSocketConnectable" glib:type-name="GSocketConnectable" glib:get-type="g_socket_connectable_get_type" glib:type-struct="SocketConnectableIface"> + <doc xml:space="preserve">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; + } +} +]|</doc> + <virtual-method name="enumerate" invoker="enumerate" version="2.22"> + <doc xml:space="preserve">Creates a #GSocketAddressEnumerator for @connectable.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSocketAddressEnumerator.</doc> + <type name="SocketAddressEnumerator" c:type="GSocketAddressEnumerator*"/> + </return-value> + <parameters> + <instance-parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="proxy_enumerate" invoker="proxy_enumerate" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSocketAddressEnumerator.</doc> + <type name="SocketAddressEnumerator" c:type="GSocketAddressEnumerator*"/> + </return-value> + <parameters> + <instance-parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="to_string" invoker="to_string" version="2.48"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the formatted string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="enumerate" c:identifier="g_socket_connectable_enumerate" version="2.22"> + <doc xml:space="preserve">Creates a #GSocketAddressEnumerator for @connectable.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSocketAddressEnumerator.</doc> + <type name="SocketAddressEnumerator" c:type="GSocketAddressEnumerator*"/> + </return-value> + <parameters> + <instance-parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </instance-parameter> + </parameters> + </method> + <method name="proxy_enumerate" c:identifier="g_socket_connectable_proxy_enumerate" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSocketAddressEnumerator.</doc> + <type name="SocketAddressEnumerator" c:type="GSocketAddressEnumerator*"/> + </return-value> + <parameters> + <instance-parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </instance-parameter> + </parameters> + </method> + <method name="to_string" c:identifier="g_socket_connectable_to_string" version="2.48"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the formatted string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </instance-parameter> + </parameters> + </method> + </interface> + <record name="SocketConnectableIface" c:type="GSocketConnectableIface" glib:is-gtype-struct-for="SocketConnectable"> + <doc xml:space="preserve">Provides an interface for returning a #GSocketAddressEnumerator +and #GProxyAddressEnumerator</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="enumerate"> + <callback name="enumerate"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSocketAddressEnumerator.</doc> + <type name="SocketAddressEnumerator" c:type="GSocketAddressEnumerator*"/> + </return-value> + <parameters> + <parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="proxy_enumerate"> + <callback name="proxy_enumerate"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSocketAddressEnumerator.</doc> + <type name="SocketAddressEnumerator" c:type="GSocketAddressEnumerator*"/> + </return-value> + <parameters> + <parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="to_string"> + <callback name="to_string"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the formatted string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="connectable" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="SocketConnection" c:symbol-prefix="socket_connection" c:type="GSocketConnection" version="2.22" parent="IOStream" glib:type-name="GSocketConnection" glib:get-type="g_socket_connection_get_type" glib:type-struct="SocketConnectionClass"> + <doc xml:space="preserve">#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.</doc> + <function name="factory_lookup_type" c:identifier="g_socket_connection_factory_lookup_type" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GType</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <parameter name="family" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketFamily</doc> + <type name="SocketFamily" c:type="GSocketFamily"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketType</doc> + <type name="SocketType" c:type="GSocketType"/> + </parameter> + <parameter name="protocol_id" transfer-ownership="none"> + <doc xml:space="preserve">a protocol id</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="factory_register_type" c:identifier="g_socket_connection_factory_register_type" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="g_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="family" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketFamily</doc> + <type name="SocketFamily" c:type="GSocketFamily"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketType</doc> + <type name="SocketType" c:type="GSocketType"/> + </parameter> + <parameter name="protocol" transfer-ownership="none"> + <doc xml:space="preserve">a protocol id</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <method name="connect" c:identifier="g_socket_connection_connect" version="2.32" throws="1"> + <doc xml:space="preserve">Connect @connection to the specified remote address.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the connection succeeded, %FALSE on error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnection</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </instance-parameter> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddress specifying the remote address.</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="connect_async" c:identifier="g_socket_connection_connect_async" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnection</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </instance-parameter> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddress specifying the remote address.</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data for the callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="connect_finish" c:identifier="g_socket_connection_connect_finish" version="2.32" throws="1"> + <doc xml:space="preserve">Gets the result of a g_socket_connection_connect_async() call.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the connection succeeded, %FALSE on error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnection</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="get_local_address" c:identifier="g_socket_connection_get_local_address" version="2.22" throws="1"> + <doc xml:space="preserve">Try to get the local address of a socket connection.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketAddress or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnection</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_remote_address" c:identifier="g_socket_connection_get_remote_address" version="2.22" throws="1"> + <doc xml:space="preserve">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)...".</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketAddress or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnection</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_socket" c:identifier="g_socket_connection_get_socket" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GSocket or %NULL on error.</doc> + <type name="Socket" c:type="GSocket*"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnection</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_connected" c:identifier="g_socket_connection_is_connected" version="2.32"> + <doc xml:space="preserve">Checks if @connection is connected. This is equivalent to calling +g_socket_is_connected() on @connection's underlying #GSocket.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether @connection is connected</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnection</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </instance-parameter> + </parameters> + </method> + <property name="socket" writable="1" construct-only="1" transfer-ownership="none"> + <type name="Socket"/> + </property> + <field name="parent_instance"> + <type name="IOStream" c:type="GIOStream"/> + </field> + <field name="priv"> + <type name="SocketConnectionPrivate" c:type="GSocketConnectionPrivate*"/> + </field> + </class> + <record name="SocketConnectionClass" c:type="GSocketConnectionClass" glib:is-gtype-struct-for="SocketConnection"> + <field name="parent_class"> + <type name="IOStreamClass" c:type="GIOStreamClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved6" introspectable="0"> + <callback name="_g_reserved6"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="SocketConnectionPrivate" c:type="GSocketConnectionPrivate" disguised="1"/> + <class name="SocketControlMessage" c:symbol-prefix="socket_control_message" c:type="GSocketControlMessage" version="2.22" parent="GObject.Object" abstract="1" glib:type-name="GSocketControlMessage" glib:get-type="g_socket_control_message_get_type" glib:type-struct="SocketControlMessageClass"> + <doc xml:space="preserve">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.</doc> + <function name="deserialize" c:identifier="g_socket_control_message_deserialize" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the deserialized message or %NULL</doc> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </return-value> + <parameters> + <parameter name="level" transfer-ownership="none"> + <doc xml:space="preserve">a socket level</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a socket control message type for the given @level</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="size" transfer-ownership="none"> + <doc xml:space="preserve">the size of the data in bytes</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">pointer to the message data</doc> + <array length="2" zero-terminated="0" c:type="gpointer"> + <type name="guint8"/> + </array> + </parameter> + </parameters> + </function> + <virtual-method name="get_level" invoker="get_level" version="2.22"> + <doc xml:space="preserve">Returns the "level" (i.e. the originating protocol) of the control message. +This is often SOL_SOCKET.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an integer describing the level</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketControlMessage</doc> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_size" invoker="get_size" version="2.22"> + <doc xml:space="preserve">Returns the space required for the control message, not including +headers or alignment.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The number of bytes required.</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketControlMessage</doc> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_type"> + <return-value transfer-ownership="none"> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="serialize" invoker="serialize" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketControlMessage</doc> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">A buffer to write data to</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_level" c:identifier="g_socket_control_message_get_level" version="2.22"> + <doc xml:space="preserve">Returns the "level" (i.e. the originating protocol) of the control message. +This is often SOL_SOCKET.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an integer describing the level</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketControlMessage</doc> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_msg_type" c:identifier="g_socket_control_message_get_msg_type" version="2.22"> + <doc xml:space="preserve">Returns the protocol specific type of the control message. +For instance, for UNIX fd passing this would be SCM_RIGHTS.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an integer describing the type of control message</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketControlMessage</doc> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_size" c:identifier="g_socket_control_message_get_size" version="2.22"> + <doc xml:space="preserve">Returns the space required for the control message, not including +headers or alignment.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The number of bytes required.</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketControlMessage</doc> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="serialize" c:identifier="g_socket_control_message_serialize" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketControlMessage</doc> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">A buffer to write data to</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv"> + <type name="SocketControlMessagePrivate" c:type="GSocketControlMessagePrivate*"/> + </field> + </class> + <record name="SocketControlMessageClass" c:type="GSocketControlMessageClass" glib:is-gtype-struct-for="SocketControlMessage"> + <doc xml:space="preserve">Class structure for #GSocketControlMessage.</doc> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="get_size"> + <callback name="get_size"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The number of bytes required.</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketControlMessage</doc> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_level"> + <callback name="get_level"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an integer describing the level</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketControlMessage</doc> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_type"> + <callback name="get_type"> + <return-value transfer-ownership="none"> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <parameter name="message" transfer-ownership="none"> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="serialize"> + <callback name="serialize"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketControlMessage</doc> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">A buffer to write data to</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="deserialize" introspectable="0"> + <callback name="deserialize" introspectable="0"> + <return-value> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </return-value> + <parameters> + <parameter name="level" transfer-ownership="none"> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="size" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="data" transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="SocketControlMessagePrivate" c:type="GSocketControlMessagePrivate" disguised="1"/> + <enumeration name="SocketFamily" version="2.22" glib:type-name="GSocketFamily" glib:get-type="g_socket_family_get_type" c:type="GSocketFamily"> + <doc xml:space="preserve">The protocol family of a #GSocketAddress. (These values are +identical to the system defines %AF_INET, %AF_INET6 and %AF_UNIX, +if available.)</doc> + <member name="invalid" value="0" c:identifier="G_SOCKET_FAMILY_INVALID" glib:nick="invalid"> + <doc xml:space="preserve">no address family</doc> + </member> + <member name="unix" value="1" c:identifier="G_SOCKET_FAMILY_UNIX" glib:nick="unix"> + <doc xml:space="preserve">the UNIX domain family</doc> + </member> + <member name="ipv4" value="2" c:identifier="G_SOCKET_FAMILY_IPV4" glib:nick="ipv4"> + <doc xml:space="preserve">the IPv4 family</doc> + </member> + <member name="ipv6" value="10" c:identifier="G_SOCKET_FAMILY_IPV6" glib:nick="ipv6"> + <doc xml:space="preserve">the IPv6 family</doc> + </member> + </enumeration> + <class name="SocketListener" c:symbol-prefix="socket_listener" c:type="GSocketListener" version="2.22" parent="GObject.Object" glib:type-name="GSocketListener" glib:get-type="g_socket_listener_get_type" glib:type-struct="SocketListenerClass"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_socket_listener_new" version="2.22"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSocketListener.</doc> + <type name="SocketListener" c:type="GSocketListener*"/> + </return-value> + </constructor> + <virtual-method name="changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="listener" transfer-ownership="none"> + <type name="SocketListener" c:type="GSocketListener*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="event"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="listener" transfer-ownership="none"> + <type name="SocketListener" c:type="GSocketListener*"/> + </instance-parameter> + <parameter name="event" transfer-ownership="none"> + <type name="SocketListenerEvent" c:type="GSocketListenerEvent"/> + </parameter> + <parameter name="socket" transfer-ownership="none"> + <type name="Socket" c:type="GSocket*"/> + </parameter> + </parameters> + </virtual-method> + <method name="accept" c:identifier="g_socket_listener_accept" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketConnection on success, %NULL on error.</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </return-value> + <parameters> + <instance-parameter name="listener" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketListener</doc> + <type name="SocketListener" c:type="GSocketListener*"/> + </instance-parameter> + <parameter name="source_object" direction="out" caller-allocates="0" transfer-ownership="none" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">location where #GObject pointer will be stored, or %NULL</doc> + <type name="GObject.Object" c:type="GObject**"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="accept_async" c:identifier="g_socket_listener_accept_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="listener" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketListener</doc> + <type name="SocketListener" c:type="GSocketListener*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data for the callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="accept_finish" c:identifier="g_socket_listener_accept_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an async accept operation. See g_socket_listener_accept_async()</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocketConnection on success, %NULL on error.</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </return-value> + <parameters> + <instance-parameter name="listener" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketListener</doc> + <type name="SocketListener" c:type="GSocketListener*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="source_object" direction="out" caller-allocates="0" transfer-ownership="none" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">Optional #GObject identifying this source</doc> + <type name="GObject.Object" c:type="GObject**"/> + </parameter> + </parameters> + </method> + <method name="accept_socket" c:identifier="g_socket_listener_accept_socket" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocket on success, %NULL on error.</doc> + <type name="Socket" c:type="GSocket*"/> + </return-value> + <parameters> + <instance-parameter name="listener" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketListener</doc> + <type name="SocketListener" c:type="GSocketListener*"/> + </instance-parameter> + <parameter name="source_object" direction="out" caller-allocates="0" transfer-ownership="none" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">location where #GObject pointer will be stored, or %NULL.</doc> + <type name="GObject.Object" c:type="GObject**"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="accept_socket_async" c:identifier="g_socket_listener_accept_socket_async" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="listener" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketListener</doc> + <type name="SocketListener" c:type="GSocketListener*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data for the callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="accept_socket_finish" c:identifier="g_socket_listener_accept_socket_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes an async accept operation. See g_socket_listener_accept_socket_async()</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GSocket on success, %NULL on error.</doc> + <type name="Socket" c:type="GSocket*"/> + </return-value> + <parameters> + <instance-parameter name="listener" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketListener</doc> + <type name="SocketListener" c:type="GSocketListener*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="source_object" direction="out" caller-allocates="0" transfer-ownership="none" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">Optional #GObject identifying this source</doc> + <type name="GObject.Object" c:type="GObject**"/> + </parameter> + </parameters> + </method> + <method name="add_address" c:identifier="g_socket_listener_add_address" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="listener" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketListener</doc> + <type name="SocketListener" c:type="GSocketListener*"/> + </instance-parameter> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketAddress</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketType</doc> + <type name="SocketType" c:type="GSocketType"/> + </parameter> + <parameter name="protocol" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketProtocol</doc> + <type name="SocketProtocol" c:type="GSocketProtocol"/> + </parameter> + <parameter name="source_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Optional #GObject identifying this source</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + <parameter name="effective_address" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">location to store the address that was bound to, or %NULL.</doc> + <type name="SocketAddress" c:type="GSocketAddress**"/> + </parameter> + </parameters> + </method> + <method name="add_any_inet_port" c:identifier="g_socket_listener_add_any_inet_port" version="2.24" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the port number, or 0 in case of failure.</doc> + <type name="guint16" c:type="guint16"/> + </return-value> + <parameters> + <instance-parameter name="listener" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketListener</doc> + <type name="SocketListener" c:type="GSocketListener*"/> + </instance-parameter> + <parameter name="source_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Optional #GObject identifying this source</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + </parameters> + </method> + <method name="add_inet_port" c:identifier="g_socket_listener_add_inet_port" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="listener" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketListener</doc> + <type name="SocketListener" c:type="GSocketListener*"/> + </instance-parameter> + <parameter name="port" transfer-ownership="none"> + <doc xml:space="preserve">an IP port number (non-zero)</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + <parameter name="source_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Optional #GObject identifying this source</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + </parameters> + </method> + <method name="add_socket" c:identifier="g_socket_listener_add_socket" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="listener" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketListener</doc> + <type name="SocketListener" c:type="GSocketListener*"/> + </instance-parameter> + <parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">a listening #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </parameter> + <parameter name="source_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Optional #GObject identifying this source</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + </parameters> + </method> + <method name="close" c:identifier="g_socket_listener_close" version="2.22"> + <doc xml:space="preserve">Closes all the sockets in the listener.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="listener" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketListener</doc> + <type name="SocketListener" c:type="GSocketListener*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_backlog" c:identifier="g_socket_listener_set_backlog" version="2.22"> + <doc xml:space="preserve">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</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="listener" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketListener</doc> + <type name="SocketListener" c:type="GSocketListener*"/> + </instance-parameter> + <parameter name="listen_backlog" transfer-ownership="none"> + <doc xml:space="preserve">an integer</doc> + <type name="gint" c:type="int"/> + </parameter> + </parameters> + </method> + <property name="listen-backlog" writable="1" construct="1" transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv"> + <type name="SocketListenerPrivate" c:type="GSocketListenerPrivate*"/> + </field> + <glib:signal name="event" when="last" version="2.46"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="event" transfer-ownership="none"> + <doc xml:space="preserve">the event that is occurring</doc> + <type name="SocketListenerEvent"/> + </parameter> + <parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">the #GSocket the event is occurring on</doc> + <type name="Socket"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="SocketListenerClass" c:type="GSocketListenerClass" glib:is-gtype-struct-for="SocketListener"> + <doc xml:space="preserve">Class structure for #GSocketListener.</doc> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="changed"> + <callback name="changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="listener" transfer-ownership="none"> + <type name="SocketListener" c:type="GSocketListener*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="event"> + <callback name="event"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="listener" transfer-ownership="none"> + <type name="SocketListener" c:type="GSocketListener*"/> + </parameter> + <parameter name="event" transfer-ownership="none"> + <type name="SocketListenerEvent" c:type="GSocketListenerEvent"/> + </parameter> + <parameter name="socket" transfer-ownership="none"> + <type name="Socket" c:type="GSocket*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved6" introspectable="0"> + <callback name="_g_reserved6"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <enumeration name="SocketListenerEvent" version="2.46" glib:type-name="GSocketListenerEvent" glib:get-type="g_socket_listener_event_get_type" c:type="GSocketListenerEvent"> + <doc xml:space="preserve">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.</doc> + <member name="binding" value="0" c:identifier="G_SOCKET_LISTENER_BINDING" glib:nick="binding"> + <doc xml:space="preserve">The listener is about to bind a socket.</doc> + </member> + <member name="bound" value="1" c:identifier="G_SOCKET_LISTENER_BOUND" glib:nick="bound"> + <doc xml:space="preserve">The listener has bound a socket.</doc> + </member> + <member name="listening" value="2" c:identifier="G_SOCKET_LISTENER_LISTENING" glib:nick="listening"> + <doc xml:space="preserve">The listener is about to start + listening on this socket.</doc> + </member> + <member name="listened" value="3" c:identifier="G_SOCKET_LISTENER_LISTENED" glib:nick="listened"> + <doc xml:space="preserve">The listener is now listening on + this socket.</doc> + </member> + </enumeration> + <record name="SocketListenerPrivate" c:type="GSocketListenerPrivate" disguised="1"/> + <bitfield name="SocketMsgFlags" version="2.22" glib:type-name="GSocketMsgFlags" glib:get-type="g_socket_msg_flags_get_type" c:type="GSocketMsgFlags"> + <doc xml:space="preserve">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.</doc> + <member name="none" value="0" c:identifier="G_SOCKET_MSG_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags.</doc> + </member> + <member name="oob" value="1" c:identifier="G_SOCKET_MSG_OOB" glib:nick="oob"> + <doc xml:space="preserve">Request to send/receive out of band data.</doc> + </member> + <member name="peek" value="2" c:identifier="G_SOCKET_MSG_PEEK" glib:nick="peek"> + <doc xml:space="preserve">Read data from the socket without removing it from + the queue.</doc> + </member> + <member name="dontroute" value="4" c:identifier="G_SOCKET_MSG_DONTROUTE" glib:nick="dontroute"> + <doc xml:space="preserve">Don't use a gateway to send out the packet, + only send to hosts on directly connected networks.</doc> + </member> + </bitfield> + <record name="SocketPrivate" c:type="GSocketPrivate" disguised="1"/> + <enumeration name="SocketProtocol" version="2.22" glib:type-name="GSocketProtocol" glib:get-type="g_socket_protocol_get_type" c:type="GSocketProtocol"> + <doc xml:space="preserve">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.</doc> + <member name="unknown" value="-1" c:identifier="G_SOCKET_PROTOCOL_UNKNOWN" glib:nick="unknown"> + <doc xml:space="preserve">The protocol type is unknown</doc> + </member> + <member name="default" value="0" c:identifier="G_SOCKET_PROTOCOL_DEFAULT" glib:nick="default"> + <doc xml:space="preserve">The default protocol for the family/type</doc> + </member> + <member name="tcp" value="6" c:identifier="G_SOCKET_PROTOCOL_TCP" glib:nick="tcp"> + <doc xml:space="preserve">TCP over IP</doc> + </member> + <member name="udp" value="17" c:identifier="G_SOCKET_PROTOCOL_UDP" glib:nick="udp"> + <doc xml:space="preserve">UDP over IP</doc> + </member> + <member name="sctp" value="132" c:identifier="G_SOCKET_PROTOCOL_SCTP" glib:nick="sctp"> + <doc xml:space="preserve">SCTP over IP</doc> + </member> + </enumeration> + <class name="SocketService" c:symbol-prefix="socket_service" c:type="GSocketService" version="2.22" parent="SocketListener" glib:type-name="GSocketService" glib:get-type="g_socket_service_get_type" glib:type-struct="SocketServiceClass"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_socket_service_new" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSocketService.</doc> + <type name="SocketService" c:type="GSocketService*"/> + </return-value> + </constructor> + <virtual-method name="incoming"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="service" transfer-ownership="none"> + <type name="SocketService" c:type="GSocketService*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none"> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </parameter> + <parameter name="source_object" transfer-ownership="none"> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + </parameters> + </virtual-method> + <method name="is_active" c:identifier="g_socket_service_is_active" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the service is active, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="service" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketService</doc> + <type name="SocketService" c:type="GSocketService*"/> + </instance-parameter> + </parameters> + </method> + <method name="start" c:identifier="g_socket_service_start" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="service" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketService</doc> + <type name="SocketService" c:type="GSocketService*"/> + </instance-parameter> + </parameters> + </method> + <method name="stop" c:identifier="g_socket_service_stop" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="service" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketService</doc> + <type name="SocketService" c:type="GSocketService*"/> + </instance-parameter> + </parameters> + </method> + <property name="active" version="2.46" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">Whether the service is currently accepting connections.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <field name="parent_instance"> + <type name="SocketListener" c:type="GSocketListener"/> + </field> + <field name="priv"> + <type name="SocketServicePrivate" c:type="GSocketServicePrivate*"/> + </field> + <glib:signal name="incoming" when="last" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop other handlers from being called</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a new #GSocketConnection object</doc> + <type name="SocketConnection"/> + </parameter> + <parameter name="source_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the source_object passed to + g_socket_listener_add_address()</doc> + <type name="GObject.Object"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="SocketServiceClass" c:type="GSocketServiceClass" glib:is-gtype-struct-for="SocketService"> + <doc xml:space="preserve">Class structure for #GSocketService.</doc> + <field name="parent_class"> + <type name="SocketListenerClass" c:type="GSocketListenerClass"/> + </field> + <field name="incoming"> + <callback name="incoming"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="service" transfer-ownership="none"> + <type name="SocketService" c:type="GSocketService*"/> + </parameter> + <parameter name="connection" transfer-ownership="none"> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </parameter> + <parameter name="source_object" transfer-ownership="none"> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved6" introspectable="0"> + <callback name="_g_reserved6"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="SocketServicePrivate" c:type="GSocketServicePrivate" disguised="1"/> + <callback name="SocketSourceFunc" c:type="GSocketSourceFunc" version="2.22"> + <doc xml:space="preserve">This is the function type of the callback used for the #GSource +returned by g_socket_create_source().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">it should return %FALSE if the source should be removed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">the #GSocket</doc> + <type name="Socket" c:type="GSocket*"/> + </parameter> + <parameter name="condition" transfer-ownership="none"> + <doc xml:space="preserve">the current condition at the source fired.</doc> + <type name="GLib.IOCondition" c:type="GIOCondition"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">data passed in by the user.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <enumeration name="SocketType" version="2.22" glib:type-name="GSocketType" glib:get-type="g_socket_type_get_type" c:type="GSocketType"> + <doc xml:space="preserve">Flags used when creating a #GSocket. Some protocols may not implement +all the socket types.</doc> + <member name="invalid" value="0" c:identifier="G_SOCKET_TYPE_INVALID" glib:nick="invalid"> + <doc xml:space="preserve">Type unknown or wrong</doc> + </member> + <member name="stream" value="1" c:identifier="G_SOCKET_TYPE_STREAM" glib:nick="stream"> + <doc xml:space="preserve">Reliable connection-based byte streams (e.g. TCP).</doc> + </member> + <member name="datagram" value="2" c:identifier="G_SOCKET_TYPE_DATAGRAM" glib:nick="datagram"> + <doc xml:space="preserve">Connectionless, unreliable datagram passing. + (e.g. UDP)</doc> + </member> + <member name="seqpacket" value="3" c:identifier="G_SOCKET_TYPE_SEQPACKET" glib:nick="seqpacket"> + <doc xml:space="preserve">Reliable connection-based passing of datagrams + of fixed maximum length (e.g. SCTP).</doc> + </member> + </enumeration> + <record name="SrvTarget" c:type="GSrvTarget" glib:type-name="GSrvTarget" glib:get-type="g_srv_target_get_type" c:symbol-prefix="srv_target"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_srv_target_new" version="2.22"> + <doc xml:space="preserve">Creates a new #GSrvTarget with the given parameters. + +You should not need to use this; normally #GSrvTargets are +created by #GResolver.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSrvTarget.</doc> + <type name="SrvTarget" c:type="GSrvTarget*"/> + </return-value> + <parameters> + <parameter name="hostname" transfer-ownership="none"> + <doc xml:space="preserve">the host that the service is running on</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="port" transfer-ownership="none"> + <doc xml:space="preserve">the port that the service is running on</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + <parameter name="priority" transfer-ownership="none"> + <doc xml:space="preserve">the target's priority</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + <parameter name="weight" transfer-ownership="none"> + <doc xml:space="preserve">the target's weight</doc> + <type name="guint16" c:type="guint16"/> + </parameter> + </parameters> + </constructor> + <method name="copy" c:identifier="g_srv_target_copy" version="2.22"> + <doc xml:space="preserve">Copies @target</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a copy of @target</doc> + <type name="SrvTarget" c:type="GSrvTarget*"/> + </return-value> + <parameters> + <instance-parameter name="target" transfer-ownership="none"> + <doc xml:space="preserve">a #GSrvTarget</doc> + <type name="SrvTarget" c:type="GSrvTarget*"/> + </instance-parameter> + </parameters> + </method> + <method name="free" c:identifier="g_srv_target_free" version="2.22"> + <doc xml:space="preserve">Frees @target</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="target" transfer-ownership="none"> + <doc xml:space="preserve">a #GSrvTarget</doc> + <type name="SrvTarget" c:type="GSrvTarget*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_hostname" c:identifier="g_srv_target_get_hostname" version="2.22"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@target's hostname</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="target" transfer-ownership="none"> + <doc xml:space="preserve">a #GSrvTarget</doc> + <type name="SrvTarget" c:type="GSrvTarget*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_port" c:identifier="g_srv_target_get_port" version="2.22"> + <doc xml:space="preserve">Gets @target's port</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@target's port</doc> + <type name="guint16" c:type="guint16"/> + </return-value> + <parameters> + <instance-parameter name="target" transfer-ownership="none"> + <doc xml:space="preserve">a #GSrvTarget</doc> + <type name="SrvTarget" c:type="GSrvTarget*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_priority" c:identifier="g_srv_target_get_priority" version="2.22"> + <doc xml:space="preserve">Gets @target's priority. You should not need to look at this; +#GResolver already sorts the targets according to the algorithm in +RFC 2782.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@target's priority</doc> + <type name="guint16" c:type="guint16"/> + </return-value> + <parameters> + <instance-parameter name="target" transfer-ownership="none"> + <doc xml:space="preserve">a #GSrvTarget</doc> + <type name="SrvTarget" c:type="GSrvTarget*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_weight" c:identifier="g_srv_target_get_weight" version="2.22"> + <doc xml:space="preserve">Gets @target's weight. You should not need to look at this; +#GResolver already sorts the targets according to the algorithm in +RFC 2782.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@target's weight</doc> + <type name="guint16" c:type="guint16"/> + </return-value> + <parameters> + <instance-parameter name="target" transfer-ownership="none"> + <doc xml:space="preserve">a #GSrvTarget</doc> + <type name="SrvTarget" c:type="GSrvTarget*"/> + </instance-parameter> + </parameters> + </method> + <function name="list_sort" c:identifier="g_srv_target_list_sort" version="2.22" introspectable="0"> + <doc xml:space="preserve">Sorts @targets in place according to the algorithm in RFC 2782.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the head of the sorted list.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="targets" transfer-ownership="none"> + <doc xml:space="preserve">a #GList of #GSrvTarget</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + </record> + <record name="StaticResource" c:type="GStaticResource"> + <doc xml:space="preserve">#GStaticResource is an opaque data structure and can only be accessed +using the following functions.</doc> + <field name="data" readable="0" private="1"> + <type name="guint8" c:type="const guint8*"/> + </field> + <field name="data_len" readable="0" private="1"> + <type name="gsize" c:type="gsize"/> + </field> + <field name="resource" readable="0" private="1"> + <type name="Resource" c:type="GResource*"/> + </field> + <field name="next" readable="0" private="1"> + <type name="StaticResource" c:type="GStaticResource*"/> + </field> + <field name="padding" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <method name="fini" c:identifier="g_static_resource_fini" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="static_resource" transfer-ownership="none"> + <doc xml:space="preserve">pointer to a static #GStaticResource</doc> + <type name="StaticResource" c:type="GStaticResource*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_resource" c:identifier="g_static_resource_get_resource" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GResource</doc> + <type name="Resource" c:type="GResource*"/> + </return-value> + <parameters> + <instance-parameter name="static_resource" transfer-ownership="none"> + <doc xml:space="preserve">pointer to a static #GStaticResource</doc> + <type name="StaticResource" c:type="GStaticResource*"/> + </instance-parameter> + </parameters> + </method> + <method name="init" c:identifier="g_static_resource_init" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="static_resource" transfer-ownership="none"> + <doc xml:space="preserve">pointer to a static #GStaticResource</doc> + <type name="StaticResource" c:type="GStaticResource*"/> + </instance-parameter> + </parameters> + </method> + </record> + <class name="Subprocess" c:symbol-prefix="subprocess" c:type="GSubprocess" version="2.40" parent="GObject.Object" glib:type-name="GSubprocess" glib:get-type="g_subprocess_get_type"> + <doc xml:space="preserve">#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).</doc> + <implements name="Initable"/> + <constructor name="new" c:identifier="g_subprocess_new" shadowed-by="newv" version="2.40" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A newly created #GSubprocess, or %NULL on error (and @error + will be set)</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </return-value> + <parameters> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags that define the behaviour of the subprocess</doc> + <type name="SubprocessFlags" c:type="GSubprocessFlags"/> + </parameter> + <parameter name="error" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">return location for an error, or %NULL</doc> + <type name="GLib.Error" c:type="GError**"/> + </parameter> + <parameter name="argv0" transfer-ownership="none"> + <doc xml:space="preserve">first commandline argument to pass to the subprocess</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">more commandline arguments, followed by %NULL</doc> + <varargs/> + </parameter> + </parameters> + </constructor> + <constructor name="newv" c:identifier="g_subprocess_newv" shadows="new" version="2.40" throws="1"> + <doc xml:space="preserve">Create a new process with the given flags and argument list. + +The argument list is expected to be %NULL-terminated.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A newly created #GSubprocess, or %NULL on error (and @error + will be set)</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </return-value> + <parameters> + <parameter name="argv" transfer-ownership="none"> + <doc xml:space="preserve">commandline arguments for the subprocess</doc> + <array c:type="const gchar* const*"> + <type name="filename"/> + </array> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags that define the behaviour of the subprocess</doc> + <type name="SubprocessFlags" c:type="GSubprocessFlags"/> + </parameter> + </parameters> + </constructor> + <method name="communicate" c:identifier="g_subprocess_communicate" version="2.40" throws="1"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + <parameter name="stdin_buf" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to send to the stdin of the subprocess, or %NULL</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="stdout_buf" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">data read from the subprocess stdout</doc> + <type name="GLib.Bytes" c:type="GBytes**"/> + </parameter> + <parameter name="stderr_buf" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">data read from the subprocess stderr</doc> + <type name="GLib.Bytes" c:type="GBytes**"/> + </parameter> + </parameters> + </method> + <method name="communicate_async" c:identifier="g_subprocess_communicate_async"> + <doc xml:space="preserve">Asynchronous version of g_subprocess_communicate(). Complete +invocation with g_subprocess_communicate_finish().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">Self</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + <parameter name="stdin_buf" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Input data, or %NULL</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Cancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">Callback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">User data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="communicate_finish" c:identifier="g_subprocess_communicate_finish" throws="1"> + <doc xml:space="preserve">Complete an invocation of g_subprocess_communicate_async().</doc> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">Self</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">Result</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="stdout_buf" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">Return location for stdout data</doc> + <type name="GLib.Bytes" c:type="GBytes**"/> + </parameter> + <parameter name="stderr_buf" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">Return location for stderr data</doc> + <type name="GLib.Bytes" c:type="GBytes**"/> + </parameter> + </parameters> + </method> + <method name="communicate_utf8" c:identifier="g_subprocess_communicate_utf8" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + <parameter name="stdin_buf" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to send to the stdin of the subprocess, or %NULL</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="stdout_buf" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">data read from the subprocess stdout</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="stderr_buf" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">data read from the subprocess stderr</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="communicate_utf8_async" c:identifier="g_subprocess_communicate_utf8_async"> + <doc xml:space="preserve">Asynchronous version of g_subprocess_communicate_utf8(). Complete +invocation with g_subprocess_communicate_utf8_finish().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">Self</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + <parameter name="stdin_buf" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Input data, or %NULL</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Cancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">Callback</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">User data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="communicate_utf8_finish" c:identifier="g_subprocess_communicate_utf8_finish" throws="1"> + <doc xml:space="preserve">Complete an invocation of g_subprocess_communicate_utf8_async().</doc> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">Self</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">Result</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="stdout_buf" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">Return location for stdout data</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="stderr_buf" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">Return location for stderr data</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="force_exit" c:identifier="g_subprocess_force_exit" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_exit_status" c:identifier="g_subprocess_get_exit_status" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the exit status</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_identifier" c:identifier="g_subprocess_get_identifier" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the subprocess identifier, or %NULL if the subprocess + has terminated</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_if_exited" c:identifier="g_subprocess_get_if_exited" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the case of a normal exit</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_if_signaled" c:identifier="g_subprocess_get_if_signaled" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the case of termination due to a signal</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_status" c:identifier="g_subprocess_get_status" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the (meaningless) waitpid() exit status from the kernel</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_stderr_pipe" c:identifier="g_subprocess_get_stderr_pipe" version="2.40"> + <doc xml:space="preserve">Gets the #GInputStream from which to read the stderr output of +@subprocess. + +The process must have been created with %G_SUBPROCESS_FLAGS_STDERR_PIPE, +otherwise %NULL will be returned.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the stderr pipe</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_stdin_pipe" c:identifier="g_subprocess_get_stdin_pipe" version="2.40"> + <doc xml:space="preserve">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 and +not %G_SUBPROCESS_FLAGS_STDIN_INHERIT, otherwise %NULL will be returned.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the stdout pipe</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_stdout_pipe" c:identifier="g_subprocess_get_stdout_pipe" version="2.40"> + <doc xml:space="preserve">Gets the #GInputStream from which to read the stdout output of +@subprocess. + +The process must have been created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, +otherwise %NULL will be returned.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the stdout pipe</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_successful" c:identifier="g_subprocess_get_successful" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the process exited cleanly with a exit status of 0</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_term_sig" c:identifier="g_subprocess_get_term_sig" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the signal causing termination</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + </parameters> + </method> + <method name="send_signal" c:identifier="g_subprocess_send_signal" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + <parameter name="signal_num" transfer-ownership="none"> + <doc xml:space="preserve">the signal number to send</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="wait" c:identifier="g_subprocess_wait" version="2.40" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if @cancellable was cancelled</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="wait_async" c:identifier="g_subprocess_wait_async" version="2.40"> + <doc xml:space="preserve">Wait for the subprocess to terminate. + +This is the asynchronous version of g_subprocess_wait().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the operation is complete</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user_data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="wait_check" c:identifier="g_subprocess_wait_check" version="2.40" throws="1"> + <doc xml:space="preserve">Combines g_subprocess_wait() with g_spawn_check_exit_status().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if process exited abnormally, or +@cancellable was cancelled</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="wait_check_async" c:identifier="g_subprocess_wait_check_async" version="2.40"> + <doc xml:space="preserve">Combines g_subprocess_wait_async() with g_spawn_check_exit_status(). + +This is the asynchronous version of g_subprocess_wait_check().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the operation is complete</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user_data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="wait_check_finish" c:identifier="g_subprocess_wait_check_finish" version="2.40" throws="1"> + <doc xml:space="preserve">Collects the result of a previous call to +g_subprocess_wait_check_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful, or %FALSE with @error set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="wait_finish" c:identifier="g_subprocess_wait_finish" version="2.40" throws="1"> + <doc xml:space="preserve">Collects the result of a previous call to +g_subprocess_wait_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful, or %FALSE with @error set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="subprocess" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocess</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #GAsyncResult passed to your #GAsyncReadyCallback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <property name="argv" readable="0" writable="1" construct-only="1" transfer-ownership="none"> + <array> + <type name="utf8"/> + </array> + </property> + <property name="flags" readable="0" writable="1" construct-only="1" transfer-ownership="none"> + <type name="SubprocessFlags"/> + </property> + </class> + <bitfield name="SubprocessFlags" version="2.40" glib:type-name="GSubprocessFlags" glib:get-type="g_subprocess_flags_get_type" c:type="GSubprocessFlags"> + <doc xml:space="preserve">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.</doc> + <member name="none" value="0" c:identifier="G_SUBPROCESS_FLAGS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags.</doc> + </member> + <member name="stdin_pipe" value="1" c:identifier="G_SUBPROCESS_FLAGS_STDIN_PIPE" glib:nick="stdin-pipe"> + <doc xml:space="preserve">create a pipe for the stdin of the + spawned process that can be accessed with + g_subprocess_get_stdin_pipe().</doc> + </member> + <member name="stdin_inherit" value="2" c:identifier="G_SUBPROCESS_FLAGS_STDIN_INHERIT" glib:nick="stdin-inherit"> + <doc xml:space="preserve">stdin is inherited from the + calling process.</doc> + </member> + <member name="stdout_pipe" value="4" c:identifier="G_SUBPROCESS_FLAGS_STDOUT_PIPE" glib:nick="stdout-pipe"> + <doc xml:space="preserve">create a pipe for the stdout of the + spawned process that can be accessed with + g_subprocess_get_stdout_pipe().</doc> + </member> + <member name="stdout_silence" value="8" c:identifier="G_SUBPROCESS_FLAGS_STDOUT_SILENCE" glib:nick="stdout-silence"> + <doc xml:space="preserve">silence the stdout of the spawned + process (ie: redirect to `/dev/null`).</doc> + </member> + <member name="stderr_pipe" value="16" c:identifier="G_SUBPROCESS_FLAGS_STDERR_PIPE" glib:nick="stderr-pipe"> + <doc xml:space="preserve">create a pipe for the stderr of the + spawned process that can be accessed with + g_subprocess_get_stderr_pipe().</doc> + </member> + <member name="stderr_silence" value="32" c:identifier="G_SUBPROCESS_FLAGS_STDERR_SILENCE" glib:nick="stderr-silence"> + <doc xml:space="preserve">silence the stderr of the spawned + process (ie: redirect to `/dev/null`).</doc> + </member> + <member name="stderr_merge" value="64" c:identifier="G_SUBPROCESS_FLAGS_STDERR_MERGE" glib:nick="stderr-merge"> + <doc xml:space="preserve">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.</doc> + </member> + <member name="inherit_fds" value="128" c:identifier="G_SUBPROCESS_FLAGS_INHERIT_FDS" glib:nick="inherit-fds"> + <doc xml:space="preserve">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).</doc> + </member> + </bitfield> + <class name="SubprocessLauncher" c:symbol-prefix="subprocess_launcher" c:type="GSubprocessLauncher" version="2.40" parent="GObject.Object" glib:type-name="GSubprocessLauncher" glib:get-type="g_subprocess_launcher_get_type"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_subprocess_launcher_new" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </return-value> + <parameters> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">#GSubprocessFlags</doc> + <type name="SubprocessFlags" c:type="GSubprocessFlags"/> + </parameter> + </parameters> + </constructor> + <method name="getenv" c:identifier="g_subprocess_launcher_getenv" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the value of the environment variable, + %NULL if unset</doc> + <type name="filename" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocessLauncher</doc> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </instance-parameter> + <parameter name="variable" transfer-ownership="none"> + <doc xml:space="preserve">the environment variable to get</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_child_setup" c:identifier="g_subprocess_launcher_set_child_setup" version="2.40" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocessLauncher</doc> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </instance-parameter> + <parameter name="child_setup" transfer-ownership="none" scope="notified" closure="1" destroy="2"> + <doc xml:space="preserve">a #GSpawnChildSetupFunc to use as the child setup function</doc> + <type name="GLib.SpawnChildSetupFunc" c:type="GSpawnChildSetupFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data for @child_setup</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy_notify" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">a #GDestroyNotify for @user_data</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="set_cwd" c:identifier="g_subprocess_launcher_set_cwd" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocessLauncher</doc> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </instance-parameter> + <parameter name="cwd" transfer-ownership="none"> + <doc xml:space="preserve">the cwd for launched processes</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_environ" c:identifier="g_subprocess_launcher_set_environ" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocessLauncher</doc> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </instance-parameter> + <parameter name="env" transfer-ownership="none"> + <doc xml:space="preserve"> + the replacement environment</doc> + <array c:type="gchar**"> + <type name="filename"/> + </array> + </parameter> + </parameters> + </method> + <method name="set_flags" c:identifier="g_subprocess_launcher_set_flags" version="2.40"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocessLauncher</doc> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">#GSubprocessFlags</doc> + <type name="SubprocessFlags" c:type="GSubprocessFlags"/> + </parameter> + </parameters> + </method> + <method name="set_stderr_file_path" c:identifier="g_subprocess_launcher_set_stderr_file_path" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocessLauncher</doc> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a filename or %NULL</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_stdin_file_path" c:identifier="g_subprocess_launcher_set_stdin_file_path" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocessLauncher</doc> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_stdout_file_path" c:identifier="g_subprocess_launcher_set_stdout_file_path" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocessLauncher</doc> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a filename or %NULL</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="setenv" c:identifier="g_subprocess_launcher_setenv" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocessLauncher</doc> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </instance-parameter> + <parameter name="variable" transfer-ownership="none"> + <doc xml:space="preserve">the environment variable to set, + must not contain '='</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the new value for the variable</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="overwrite" transfer-ownership="none"> + <doc xml:space="preserve">whether to change the variable if it already exists</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="spawn" c:identifier="g_subprocess_launcher_spawn" version="2.40" introspectable="0"> + <doc xml:space="preserve">Creates a #GSubprocess given a provided varargs list of arguments.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A new #GSubprocess, or %NULL on error (and @error will be set)</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocessLauncher</doc> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </instance-parameter> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">Error</doc> + <type name="GLib.Error" c:type="GError**"/> + </parameter> + <parameter name="argv0" transfer-ownership="none"> + <doc xml:space="preserve">Command line arguments</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">Continued arguments, %NULL terminated</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="spawnv" c:identifier="g_subprocess_launcher_spawnv" version="2.40" throws="1"> + <doc xml:space="preserve">Creates a #GSubprocess given a provided array of arguments.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A new #GSubprocess, or %NULL on error (and @error will be set)</doc> + <type name="Subprocess" c:type="GSubprocess*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocessLauncher</doc> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </instance-parameter> + <parameter name="argv" transfer-ownership="none"> + <doc xml:space="preserve">Command line arguments</doc> + <array c:type="const gchar* const*"> + <type name="filename"/> + </array> + </parameter> + </parameters> + </method> + <method name="take_fd" c:identifier="g_subprocess_launcher_take_fd"> + <doc xml:space="preserve">Transfer an arbitrary file descriptor from parent process to the +child. This function takes ownership of the @source_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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocessLauncher</doc> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </instance-parameter> + <parameter name="source_fd" transfer-ownership="none"> + <doc xml:space="preserve">File descriptor in parent process</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="target_fd" transfer-ownership="none"> + <doc xml:space="preserve">Target descriptor for child process</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="take_stderr_fd" c:identifier="g_subprocess_launcher_take_stderr_fd" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocessLauncher</doc> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </instance-parameter> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a file descriptor, or -1</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="take_stdin_fd" c:identifier="g_subprocess_launcher_take_stdin_fd" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocessLauncher</doc> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </instance-parameter> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a file descriptor, or -1</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="take_stdout_fd" c:identifier="g_subprocess_launcher_take_stdout_fd" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocessLauncher</doc> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </instance-parameter> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a file descriptor, or -1</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="unsetenv" c:identifier="g_subprocess_launcher_unsetenv" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GSubprocessLauncher</doc> + <type name="SubprocessLauncher" c:type="GSubprocessLauncher*"/> + </instance-parameter> + <parameter name="variable" transfer-ownership="none"> + <doc xml:space="preserve">the environment variable to unset, + must not contain '='</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <property name="flags" readable="0" writable="1" construct-only="1" transfer-ownership="none"> + <type name="SubprocessFlags"/> + </property> + </class> + <function-macro name="TASK" c:identifier="G_TASK" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TASK_CLASS" c:identifier="G_TASK_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TASK_GET_CLASS" c:identifier="G_TASK_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TCP_CONNECTION" c:identifier="G_TCP_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TCP_CONNECTION_CLASS" c:identifier="G_TCP_CONNECTION_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TCP_CONNECTION_GET_CLASS" c:identifier="G_TCP_CONNECTION_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TCP_WRAPPER_CONNECTION" c:identifier="G_TCP_WRAPPER_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TCP_WRAPPER_CONNECTION_CLASS" c:identifier="G_TCP_WRAPPER_CONNECTION_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TCP_WRAPPER_CONNECTION_GET_CLASS" c:identifier="G_TCP_WRAPPER_CONNECTION_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TEST_DBUS" c:identifier="G_TEST_DBUS" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="THEMED_ICON" c:identifier="G_THEMED_ICON" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="THEMED_ICON_CLASS" c:identifier="G_THEMED_ICON_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="THEMED_ICON_GET_CLASS" c:identifier="G_THEMED_ICON_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="THREADED_SOCKET_SERVICE" c:identifier="G_THREADED_SOCKET_SERVICE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="THREADED_SOCKET_SERVICE_CLASS" c:identifier="G_THREADED_SOCKET_SERVICE_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="THREADED_SOCKET_SERVICE_GET_CLASS" c:identifier="G_THREADED_SOCKET_SERVICE_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_BACKEND" c:identifier="G_TLS_BACKEND" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <constant name="TLS_BACKEND_EXTENSION_POINT_NAME" value="gio-tls-backend" c:type="G_TLS_BACKEND_EXTENSION_POINT_NAME"> + <doc xml:space="preserve">Extension point for TLS functionality via #GTlsBackend. +See [Extending GIO][extending-gio].</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="TLS_BACKEND_GET_INTERFACE" c:identifier="G_TLS_BACKEND_GET_INTERFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_CERTIFICATE" c:identifier="G_TLS_CERTIFICATE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_CERTIFICATE_CLASS" c:identifier="G_TLS_CERTIFICATE_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_CERTIFICATE_GET_CLASS" c:identifier="G_TLS_CERTIFICATE_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_CLIENT_CONNECTION" c:identifier="G_TLS_CLIENT_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_CLIENT_CONNECTION_GET_INTERFACE" c:identifier="G_TLS_CLIENT_CONNECTION_GET_INTERFACE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_CONNECTION" c:identifier="G_TLS_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_CONNECTION_CLASS" c:identifier="G_TLS_CONNECTION_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_CONNECTION_GET_CLASS" c:identifier="G_TLS_CONNECTION_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_DATABASE" c:identifier="G_TLS_DATABASE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_DATABASE_CLASS" c:identifier="G_TLS_DATABASE_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_DATABASE_GET_CLASS" c:identifier="G_TLS_DATABASE_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <constant name="TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT" value="1.3.6.1.5.5.7.3.2" c:type="G_TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT"> + <doc xml:space="preserve">The purpose used to verify the client certificate in a TLS connection. +Used by TLS servers.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER" value="1.3.6.1.5.5.7.3.1" c:type="G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER"> + <doc xml:space="preserve">The purpose used to verify the server certificate in a TLS connection. This +is the most common purpose in use. Used by TLS clients.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="TLS_FILE_DATABASE" c:identifier="G_TLS_FILE_DATABASE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_FILE_DATABASE_GET_INTERFACE" c:identifier="G_TLS_FILE_DATABASE_GET_INTERFACE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_INTERACTION" c:identifier="G_TLS_INTERACTION" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_INTERACTION_CLASS" c:identifier="G_TLS_INTERACTION_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_INTERACTION_GET_CLASS" c:identifier="G_TLS_INTERACTION_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_PASSWORD" c:identifier="G_TLS_PASSWORD" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_PASSWORD_CLASS" c:identifier="G_TLS_PASSWORD_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_PASSWORD_GET_CLASS" c:identifier="G_TLS_PASSWORD_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_SERVER_CONNECTION" c:identifier="G_TLS_SERVER_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TLS_SERVER_CONNECTION_GET_INTERFACE" c:identifier="G_TLS_SERVER_CONNECTION_GET_INTERFACE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_ASYNC_INITABLE" c:identifier="G_TYPE_IS_ASYNC_INITABLE" introspectable="0"> + <parameters> + <parameter name="type"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_DATAGRAM_BASED" c:identifier="G_TYPE_IS_DATAGRAM_BASED" introspectable="0"> + <parameters> + <parameter name="type"> + </parameter> + </parameters> + </function-macro> + <function-macro name="TYPE_IS_INITABLE" c:identifier="G_TYPE_IS_INITABLE" introspectable="0"> + <parameters> + <parameter name="type"> + </parameter> + </parameters> + </function-macro> + <class name="Task" c:symbol-prefix="task" c:type="GTask" parent="GObject.Object" glib:type-name="GTask" glib:get-type="g_task_get_type" glib:type-struct="TaskClass"> + <doc xml:space="preserve">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()).</doc> + <implements name="AsyncResult"/> + <constructor name="new" c:identifier="g_task_new" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GTask.</doc> + <type name="Task" c:type="GTask*"/> + </return-value> + <parameters> + <parameter name="source_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the #GObject that owns + this task, or %NULL.</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="callback_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </constructor> + <function name="is_valid" c:identifier="g_task_is_valid" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @result and @source_object are valid, %FALSE +if not</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">A #GAsyncResult</doc> + <type name="AsyncResult" c:type="gpointer"/> + </parameter> + <parameter name="source_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the source object + expected to be associated with the task</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="report_error" c:identifier="g_task_report_error" version="2.36"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="source_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the #GObject that owns + this task, or %NULL.</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="callback_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="source_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an opaque pointer indicating the source of this task</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="error" transfer-ownership="full"> + <doc xml:space="preserve">error to report</doc> + <type name="GLib.Error" c:type="GError*"/> + </parameter> + </parameters> + </function> + <function name="report_new_error" c:identifier="g_task_report_new_error" version="2.36" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="source_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the #GObject that owns + this task, or %NULL.</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="callback_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="source_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an opaque pointer indicating the source of this task</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="code" transfer-ownership="none"> + <doc xml:space="preserve">an error code.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a string with format characters.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">a list of values to insert into @format.</doc> + <varargs/> + </parameter> + </parameters> + </function> + <method name="attach_source" c:identifier="g_task_attach_source" version="2.36" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">the source to attach</doc> + <type name="GLib.Source" c:type="GSource*"/> + </parameter> + <parameter name="callback" transfer-ownership="none"> + <doc xml:space="preserve">the callback to invoke when @source triggers</doc> + <type name="GLib.SourceFunc" c:type="GSourceFunc"/> + </parameter> + </parameters> + </method> + <method name="get_cancellable" c:identifier="g_task_get_cancellable" version="2.36"> + <doc xml:space="preserve">Gets @task's #GCancellable</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@task's #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_check_cancellable" c:identifier="g_task_get_check_cancellable" version="2.36"> + <doc xml:space="preserve">Gets @task's check-cancellable flag. See +g_task_set_check_cancellable() for more details.</doc> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">the #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_completed" c:identifier="g_task_get_completed" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the task has completed, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask.</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_context" c:identifier="g_task_get_context" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@task's #GMainContext</doc> + <type name="GLib.MainContext" c:type="GMainContext*"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_name" c:identifier="g_task_get_name" version="2.60"> + <doc xml:space="preserve">Gets @task’s name. See g_task_set_name().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">@task’s name, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_priority" c:identifier="g_task_get_priority" version="2.36"> + <doc xml:space="preserve">Gets @task's priority</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@task's priority</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_return_on_cancel" c:identifier="g_task_get_return_on_cancel" version="2.36"> + <doc xml:space="preserve">Gets @task's return-on-cancel flag. See +g_task_set_return_on_cancel() for more details.</doc> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">the #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_source_object" c:identifier="g_task_get_source_object" version="2.36"> + <doc xml:space="preserve">Gets the source object from @task. Like +g_async_result_get_source_object(), but does not ref the object.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">@task's source object, or %NULL</doc> + <type name="GObject.Object" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_source_tag" c:identifier="g_task_get_source_tag" version="2.36"> + <doc xml:space="preserve">Gets @task's source tag. See g_task_set_source_tag().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">@task's source tag</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_task_data" c:identifier="g_task_get_task_data" version="2.36"> + <doc xml:space="preserve">Gets @task's `task_data`.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">@task's `task_data`.</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + </parameters> + </method> + <method name="had_error" c:identifier="g_task_had_error" version="2.36"> + <doc xml:space="preserve">Tests if @task resulted in an error.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the task resulted in an error, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask.</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + </parameters> + </method> + <method name="propagate_boolean" c:identifier="g_task_propagate_boolean" version="2.36" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the task result, or %FALSE on error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask.</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + </parameters> + </method> + <method name="propagate_int" c:identifier="g_task_propagate_int" version="2.36" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the task result, or -1 on error</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask.</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + </parameters> + </method> + <method name="propagate_pointer" c:identifier="g_task_propagate_pointer" version="2.36" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the task result, or %NULL on error</doc> + <type name="gpointer" c:type="gpointer"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + </parameters> + </method> + <method name="propagate_value" c:identifier="g_task_propagate_value" version="2.64" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @task succeeded, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + <parameter name="value" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve">return location for the #GValue</doc> + <type name="GObject.Value" c:type="GValue*"/> + </parameter> + </parameters> + </method> + <method name="return_boolean" c:identifier="g_task_return_boolean" version="2.36"> + <doc xml:space="preserve">Sets @task's result to @result and completes the task (see +g_task_return_pointer() for more discussion of exactly what this +means).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask.</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the #gboolean result of a task function.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="return_error" c:identifier="g_task_return_error" version="2.36"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask.</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + <parameter name="error" transfer-ownership="full"> + <doc xml:space="preserve">the #GError result of a task function.</doc> + <type name="GLib.Error" c:type="GError*"/> + </parameter> + </parameters> + </method> + <method name="return_error_if_cancelled" c:identifier="g_task_return_error_if_cancelled" version="2.36"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @task has been cancelled, %FALSE if not</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + </parameters> + </method> + <method name="return_int" c:identifier="g_task_return_int" version="2.36"> + <doc xml:space="preserve">Sets @task's result to @result and completes the task (see +g_task_return_pointer() for more discussion of exactly what this +means).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask.</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the integer (#gssize) result of a task function.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </method> + <method name="return_new_error" c:identifier="g_task_return_new_error" version="2.36" introspectable="0"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask.</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="code" transfer-ownership="none"> + <doc xml:space="preserve">an error code.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a string with format characters.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">a list of values to insert into @format.</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="return_pointer" c:identifier="g_task_return_pointer" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="full" nullable="1" allow-none="1"> + <doc xml:space="preserve">the pointer result of a task + function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="result_destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a #GDestroyNotify function.</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="return_value" c:identifier="g_task_return_value" version="2.64"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the #GValue result of + a task function</doc> + <type name="GObject.Value" c:type="GValue*"/> + </parameter> + </parameters> + </method> + <method name="run_in_thread" c:identifier="g_task_run_in_thread" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + <parameter name="task_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">a #GTaskThreadFunc</doc> + <type name="TaskThreadFunc" c:type="GTaskThreadFunc"/> + </parameter> + </parameters> + </method> + <method name="run_in_thread_sync" c:identifier="g_task_run_in_thread_sync" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + <parameter name="task_func" transfer-ownership="none" scope="async"> + <doc xml:space="preserve">a #GTaskThreadFunc</doc> + <type name="TaskThreadFunc" c:type="GTaskThreadFunc"/> + </parameter> + </parameters> + </method> + <method name="set_check_cancellable" c:identifier="g_task_set_check_cancellable" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">the #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + <parameter name="check_cancellable" transfer-ownership="none"> + <doc xml:space="preserve">whether #GTask will check the state of + its #GCancellable for you.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_name" c:identifier="g_task_set_name" version="2.60"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">a #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a human readable name for the task, or %NULL to unset it</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_priority" c:identifier="g_task_set_priority" version="2.36"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">the #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + <parameter name="priority" transfer-ownership="none"> + <doc xml:space="preserve">the [priority][io-priority] of the request</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="set_return_on_cancel" c:identifier="g_task_set_return_on_cancel" version="2.36"> + <doc xml:space="preserve">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 +uninterruptible 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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @task's return-on-cancel flag was changed to + match @return_on_cancel. %FALSE if @task has already been + cancelled.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">the #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + <parameter name="return_on_cancel" transfer-ownership="none"> + <doc xml:space="preserve">whether the task returns automatically when + it is cancelled.</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_source_tag" c:identifier="g_task_set_source_tag" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">the #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + <parameter name="source_tag" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an opaque pointer indicating the source of this task</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="set_task_data" c:identifier="g_task_set_task_data" version="2.36"> + <doc xml:space="preserve">Sets @task's task data (freeing the existing task data, if any).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">the #GTask</doc> + <type name="Task" c:type="GTask*"/> + </instance-parameter> + <parameter name="task_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">task-specific data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="task_data_destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">#GDestroyNotify for @task_data</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <property name="completed" version="2.44" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + </class> + <record name="TaskClass" c:type="GTaskClass" disguised="1" glib:is-gtype-struct-for="Task"/> + <callback name="TaskThreadFunc" c:type="GTaskThreadFunc" version="2.36"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="task" transfer-ownership="none"> + <doc xml:space="preserve">the #GTask</doc> + <type name="Task" c:type="GTask*"/> + </parameter> + <parameter name="source_object" transfer-ownership="none"> + <doc xml:space="preserve">@task's source object</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + <parameter name="task_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">@task's task data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">@task's #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + <class name="TcpConnection" c:symbol-prefix="tcp_connection" c:type="GTcpConnection" version="2.22" parent="SocketConnection" glib:type-name="GTcpConnection" glib:get-type="g_tcp_connection_get_type" glib:type-struct="TcpConnectionClass"> + <doc xml:space="preserve">This is the subclass of #GSocketConnection that is created +for TCP/IP sockets.</doc> + <method name="get_graceful_disconnect" c:identifier="g_tcp_connection_get_graceful_disconnect" version="2.22"> + <doc xml:space="preserve">Checks if graceful disconnects are used. See +g_tcp_connection_set_graceful_disconnect().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if graceful disconnect is used on close, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GTcpConnection</doc> + <type name="TcpConnection" c:type="GTcpConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_graceful_disconnect" c:identifier="g_tcp_connection_set_graceful_disconnect" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GTcpConnection</doc> + <type name="TcpConnection" c:type="GTcpConnection*"/> + </instance-parameter> + <parameter name="graceful_disconnect" transfer-ownership="none"> + <doc xml:space="preserve">Whether to do graceful disconnects or not</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <property name="graceful-disconnect" writable="1" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </property> + <field name="parent_instance"> + <type name="SocketConnection" c:type="GSocketConnection"/> + </field> + <field name="priv"> + <type name="TcpConnectionPrivate" c:type="GTcpConnectionPrivate*"/> + </field> + </class> + <record name="TcpConnectionClass" c:type="GTcpConnectionClass" glib:is-gtype-struct-for="TcpConnection"> + <field name="parent_class"> + <type name="SocketConnectionClass" c:type="GSocketConnectionClass"/> + </field> + </record> + <record name="TcpConnectionPrivate" c:type="GTcpConnectionPrivate" disguised="1"/> + <class name="TcpWrapperConnection" c:symbol-prefix="tcp_wrapper_connection" c:type="GTcpWrapperConnection" version="2.28" parent="TcpConnection" glib:type-name="GTcpWrapperConnection" glib:get-type="g_tcp_wrapper_connection_get_type" glib:type-struct="TcpWrapperConnectionClass"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_tcp_wrapper_connection_new" version="2.28"> + <doc xml:space="preserve">Wraps @base_io_stream and @socket together as a #GSocketConnection.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new #GSocketConnection.</doc> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </return-value> + <parameters> + <parameter name="base_io_stream" transfer-ownership="none"> + <doc xml:space="preserve">the #GIOStream to wrap</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="socket" transfer-ownership="none"> + <doc xml:space="preserve">the #GSocket associated with @base_io_stream</doc> + <type name="Socket" c:type="GSocket*"/> + </parameter> + </parameters> + </constructor> + <method name="get_base_io_stream" c:identifier="g_tcp_wrapper_connection_get_base_io_stream"> + <doc xml:space="preserve">Gets @conn's base #GIOStream</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@conn's base #GIOStream</doc> + <type name="IOStream" c:type="GIOStream*"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTcpWrapperConnection</doc> + <type name="TcpWrapperConnection" c:type="GTcpWrapperConnection*"/> + </instance-parameter> + </parameters> + </method> + <property name="base-io-stream" writable="1" construct-only="1" transfer-ownership="none"> + <type name="IOStream"/> + </property> + <field name="parent_instance"> + <type name="TcpConnection" c:type="GTcpConnection"/> + </field> + <field name="priv"> + <type name="TcpWrapperConnectionPrivate" c:type="GTcpWrapperConnectionPrivate*"/> + </field> + </class> + <record name="TcpWrapperConnectionClass" c:type="GTcpWrapperConnectionClass" glib:is-gtype-struct-for="TcpWrapperConnection"> + <field name="parent_class"> + <type name="TcpConnectionClass" c:type="GTcpConnectionClass"/> + </field> + </record> + <record name="TcpWrapperConnectionPrivate" c:type="GTcpWrapperConnectionPrivate" disguised="1"/> + <class name="TestDBus" c:symbol-prefix="test_dbus" c:type="GTestDBus" version="2.34" parent="GObject.Object" glib:type-name="GTestDBus" glib:get-type="g_test_dbus_get_type"> + <doc xml:space="preserve">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 +]|</doc> + <constructor name="new" c:identifier="g_test_dbus_new"> + <doc xml:space="preserve">Create a new #GTestDBus object.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GTestDBus.</doc> + <type name="TestDBus" c:type="GTestDBus*"/> + </return-value> + <parameters> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a #GTestDBusFlags</doc> + <type name="TestDBusFlags" c:type="GTestDBusFlags"/> + </parameter> + </parameters> + </constructor> + <function name="unset" c:identifier="g_test_dbus_unset"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </function> + <method name="add_service_dir" c:identifier="g_test_dbus_add_service_dir"> + <doc xml:space="preserve">Add a path where dbus-daemon will look up .service files. This can't be +called after g_test_dbus_up().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTestDBus</doc> + <type name="TestDBus" c:type="GTestDBus*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">path to a directory containing .service files</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="down" c:identifier="g_test_dbus_down"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTestDBus</doc> + <type name="TestDBus" c:type="GTestDBus*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_bus_address" c:identifier="g_test_dbus_get_bus_address"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the address of the bus, or %NULL.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTestDBus</doc> + <type name="TestDBus" c:type="GTestDBus*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_flags" c:identifier="g_test_dbus_get_flags"> + <doc xml:space="preserve">Get the flags of the #GTestDBus object.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the value of #GTestDBus:flags property</doc> + <type name="TestDBusFlags" c:type="GTestDBusFlags"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTestDBus</doc> + <type name="TestDBus" c:type="GTestDBus*"/> + </instance-parameter> + </parameters> + </method> + <method name="stop" c:identifier="g_test_dbus_stop"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTestDBus</doc> + <type name="TestDBus" c:type="GTestDBus*"/> + </instance-parameter> + </parameters> + </method> + <method name="up" c:identifier="g_test_dbus_up"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTestDBus</doc> + <type name="TestDBus" c:type="GTestDBus*"/> + </instance-parameter> + </parameters> + </method> + <property name="flags" version="2.34" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">#GTestDBusFlags specifying the behaviour of the D-Bus session.</doc> + <type name="TestDBusFlags"/> + </property> + </class> + <bitfield name="TestDBusFlags" version="2.34" glib:type-name="GTestDBusFlags" glib:get-type="g_test_dbus_flags_get_type" c:type="GTestDBusFlags"> + <doc xml:space="preserve">Flags to define future #GTestDBus behaviour.</doc> + <member name="none" value="0" c:identifier="G_TEST_DBUS_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags.</doc> + </member> + </bitfield> + <class name="ThemedIcon" c:symbol-prefix="themed_icon" c:type="GThemedIcon" parent="GObject.Object" glib:type-name="GThemedIcon" glib:get-type="g_themed_icon_get_type" glib:type-struct="ThemedIconClass"> + <doc xml:space="preserve">#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.</doc> + <implements name="Icon"/> + <constructor name="new" c:identifier="g_themed_icon_new"> + <doc xml:space="preserve">Creates a new themed icon for @iconname.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GThemedIcon.</doc> + <type name="ThemedIcon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="iconname" transfer-ownership="none"> + <doc xml:space="preserve">a string containing an icon name.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_names" c:identifier="g_themed_icon_new_from_names"> + <doc xml:space="preserve">Creates a new themed icon for @iconnames.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GThemedIcon</doc> + <type name="ThemedIcon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="iconnames" transfer-ownership="none"> + <doc xml:space="preserve">an array of strings containing icon names.</doc> + <array length="1" zero-terminated="0" c:type="char**"> + <type name="utf8" c:type="char*"/> + </array> + </parameter> + <parameter name="len" transfer-ownership="none"> + <doc xml:space="preserve">the length of the @iconnames array, or -1 if @iconnames is + %NULL-terminated</doc> + <type name="gint" c:type="int"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_with_default_fallbacks" c:identifier="g_themed_icon_new_with_default_fallbacks"> + <doc xml:space="preserve">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"); +]|</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GThemedIcon.</doc> + <type name="ThemedIcon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="iconname" transfer-ownership="none"> + <doc xml:space="preserve">a string containing an icon name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </constructor> + <method name="append_name" c:identifier="g_themed_icon_append_name"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GThemedIcon</doc> + <type name="ThemedIcon" c:type="GThemedIcon*"/> + </instance-parameter> + <parameter name="iconname" transfer-ownership="none"> + <doc xml:space="preserve">name of icon to append to list of icons from within @icon.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_names" c:identifier="g_themed_icon_get_names"> + <doc xml:space="preserve">Gets the names of icons from within @icon.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a list of icon names.</doc> + <array c:type="const gchar* const*"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GThemedIcon.</doc> + <type name="ThemedIcon" c:type="GThemedIcon*"/> + </instance-parameter> + </parameters> + </method> + <method name="prepend_name" c:identifier="g_themed_icon_prepend_name" version="2.18"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">a #GThemedIcon</doc> + <type name="ThemedIcon" c:type="GThemedIcon*"/> + </instance-parameter> + <parameter name="iconname" transfer-ownership="none"> + <doc xml:space="preserve">name of icon to prepend to list of icons from within @icon.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <property name="name" readable="0" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The icon name.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="names" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">A %NULL-terminated array of icon names.</doc> + <array> + <type name="utf8"/> + </array> + </property> + <property name="use-default-fallbacks" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">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 +}; +]|</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + </class> + <record name="ThemedIconClass" c:type="GThemedIconClass" disguised="1" glib:is-gtype-struct-for="ThemedIcon"/> + <class name="ThreadedSocketService" c:symbol-prefix="threaded_socket_service" c:type="GThreadedSocketService" version="2.22" parent="SocketService" glib:type-name="GThreadedSocketService" glib:get-type="g_threaded_socket_service_get_type" glib:type-struct="ThreadedSocketServiceClass"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_threaded_socket_service_new" version="2.22"> + <doc xml:space="preserve">Creates a new #GThreadedSocketService with no listeners. Listeners +must be added with one of the #GSocketListener "add" methods.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GSocketService.</doc> + <type name="SocketService" c:type="GSocketService*"/> + </return-value> + <parameters> + <parameter name="max_threads" transfer-ownership="none"> + <doc xml:space="preserve">the maximal number of threads to execute concurrently + handling incoming clients, -1 means no limit</doc> + <type name="gint" c:type="int"/> + </parameter> + </parameters> + </constructor> + <virtual-method name="run"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="service" transfer-ownership="none"> + <type name="ThreadedSocketService" c:type="GThreadedSocketService*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none"> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </parameter> + <parameter name="source_object" transfer-ownership="none"> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + </parameters> + </virtual-method> + <property name="max-threads" writable="1" construct-only="1" transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </property> + <field name="parent_instance"> + <type name="SocketService" c:type="GSocketService"/> + </field> + <field name="priv"> + <type name="ThreadedSocketServicePrivate" c:type="GThreadedSocketServicePrivate*"/> + </field> + <glib:signal name="run" when="last"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to stop further signal handlers from being called</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a new #GSocketConnection object.</doc> + <type name="SocketConnection"/> + </parameter> + <parameter name="source_object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the source_object passed to g_socket_listener_add_address().</doc> + <type name="GObject.Object"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="ThreadedSocketServiceClass" c:type="GThreadedSocketServiceClass" glib:is-gtype-struct-for="ThreadedSocketService"> + <field name="parent_class"> + <type name="SocketServiceClass" c:type="GSocketServiceClass"/> + </field> + <field name="run"> + <callback name="run"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="service" transfer-ownership="none"> + <type name="ThreadedSocketService" c:type="GThreadedSocketService*"/> + </parameter> + <parameter name="connection" transfer-ownership="none"> + <type name="SocketConnection" c:type="GSocketConnection*"/> + </parameter> + <parameter name="source_object" transfer-ownership="none"> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="ThreadedSocketServicePrivate" c:type="GThreadedSocketServicePrivate" disguised="1"/> + <enumeration name="TlsAuthenticationMode" version="2.28" glib:type-name="GTlsAuthenticationMode" glib:get-type="g_tls_authentication_mode_get_type" c:type="GTlsAuthenticationMode"> + <doc xml:space="preserve">The client authentication mode for a #GTlsServerConnection.</doc> + <member name="none" value="0" c:identifier="G_TLS_AUTHENTICATION_NONE" glib:nick="none"> + <doc xml:space="preserve">client authentication not required</doc> + </member> + <member name="requested" value="1" c:identifier="G_TLS_AUTHENTICATION_REQUESTED" glib:nick="requested"> + <doc xml:space="preserve">client authentication is requested</doc> + </member> + <member name="required" value="2" c:identifier="G_TLS_AUTHENTICATION_REQUIRED" glib:nick="required"> + <doc xml:space="preserve">client authentication is required</doc> + </member> + </enumeration> + <interface name="TlsBackend" c:symbol-prefix="tls_backend" c:type="GTlsBackend" version="2.28" glib:type-name="GTlsBackend" glib:get-type="g_tls_backend_get_type" glib:type-struct="TlsBackendInterface"> + <doc xml:space="preserve">TLS (Transport Layer Security, aka SSL) and DTLS backend.</doc> + <function name="get_default" c:identifier="g_tls_backend_get_default" version="2.28"> + <doc xml:space="preserve">Gets the default #GTlsBackend for the system.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsBackend, which will be a + dummy object if no TLS backend is available</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </return-value> + </function> + <virtual-method name="get_default_database" invoker="get_default_database" version="2.30"> + <doc xml:space="preserve">Gets the default #GTlsDatabase used to verify TLS connections.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the default database, which should be + unreffed when done.</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsBackend</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="supports_dtls" invoker="supports_dtls" version="2.48"> + <doc xml:space="preserve">Checks if DTLS is supported. DTLS support may not be available even if TLS +support is available, and vice-versa.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether DTLS is supported</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsBackend</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="supports_tls" invoker="supports_tls" version="2.28"> + <doc xml:space="preserve">Checks if TLS is supported; if this returns %FALSE for the default +#GTlsBackend, it means no "real" TLS backend is available.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether or not TLS is supported</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsBackend</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="get_certificate_type" c:identifier="g_tls_backend_get_certificate_type" version="2.28"> + <doc xml:space="preserve">Gets the #GType of @backend's #GTlsCertificate implementation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GType of @backend's #GTlsCertificate + implementation.</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsBackend</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_client_connection_type" c:identifier="g_tls_backend_get_client_connection_type" version="2.28"> + <doc xml:space="preserve">Gets the #GType of @backend's #GTlsClientConnection implementation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GType of @backend's #GTlsClientConnection + implementation.</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsBackend</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_default_database" c:identifier="g_tls_backend_get_default_database" version="2.30"> + <doc xml:space="preserve">Gets the default #GTlsDatabase used to verify TLS connections.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the default database, which should be + unreffed when done.</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsBackend</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_dtls_client_connection_type" c:identifier="g_tls_backend_get_dtls_client_connection_type" version="2.48"> + <doc xml:space="preserve">Gets the #GType of @backend’s #GDtlsClientConnection implementation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GType of @backend’s #GDtlsClientConnection + implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS.</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsBackend</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_dtls_server_connection_type" c:identifier="g_tls_backend_get_dtls_server_connection_type" version="2.48"> + <doc xml:space="preserve">Gets the #GType of @backend’s #GDtlsServerConnection implementation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GType of @backend’s #GDtlsServerConnection + implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS.</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsBackend</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_file_database_type" c:identifier="g_tls_backend_get_file_database_type" version="2.30"> + <doc xml:space="preserve">Gets the #GType of @backend's #GTlsFileDatabase implementation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GType of backend's #GTlsFileDatabase implementation.</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsBackend</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_server_connection_type" c:identifier="g_tls_backend_get_server_connection_type" version="2.28"> + <doc xml:space="preserve">Gets the #GType of @backend's #GTlsServerConnection implementation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GType of @backend's #GTlsServerConnection + implementation.</doc> + <type name="GType" c:type="GType"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsBackend</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_default_database" c:identifier="g_tls_backend_set_default_database" version="2.60"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsBackend</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </instance-parameter> + <parameter name="database" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </parameter> + </parameters> + </method> + <method name="supports_dtls" c:identifier="g_tls_backend_supports_dtls" version="2.48"> + <doc xml:space="preserve">Checks if DTLS is supported. DTLS support may not be available even if TLS +support is available, and vice-versa.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether DTLS is supported</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsBackend</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </instance-parameter> + </parameters> + </method> + <method name="supports_tls" c:identifier="g_tls_backend_supports_tls" version="2.28"> + <doc xml:space="preserve">Checks if TLS is supported; if this returns %FALSE for the default +#GTlsBackend, it means no "real" TLS backend is available.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether or not TLS is supported</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsBackend</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </instance-parameter> + </parameters> + </method> + </interface> + <record name="TlsBackendInterface" c:type="GTlsBackendInterface" glib:is-gtype-struct-for="TlsBackend" version="2.28"> + <doc xml:space="preserve">Provides an interface for describing TLS-related types.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="supports_tls"> + <callback name="supports_tls"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether or not TLS is supported</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsBackend</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_certificate_type"> + <callback name="get_certificate_type"> + <return-value transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </return-value> + </callback> + </field> + <field name="get_client_connection_type"> + <callback name="get_client_connection_type"> + <return-value transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </return-value> + </callback> + </field> + <field name="get_server_connection_type"> + <callback name="get_server_connection_type"> + <return-value transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </return-value> + </callback> + </field> + <field name="get_file_database_type"> + <callback name="get_file_database_type"> + <return-value transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </return-value> + </callback> + </field> + <field name="get_default_database"> + <callback name="get_default_database"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the default database, which should be + unreffed when done.</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </return-value> + <parameters> + <parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsBackend</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="supports_dtls"> + <callback name="supports_dtls"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether DTLS is supported</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="backend" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsBackend</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_dtls_client_connection_type"> + <callback name="get_dtls_client_connection_type"> + <return-value transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </return-value> + </callback> + </field> + <field name="get_dtls_server_connection_type"> + <callback name="get_dtls_server_connection_type"> + <return-value transfer-ownership="none"> + <type name="GType" c:type="GType"/> + </return-value> + </callback> + </field> + </record> + <class name="TlsCertificate" c:symbol-prefix="tls_certificate" c:type="GTlsCertificate" version="2.28" parent="GObject.Object" abstract="1" glib:type-name="GTlsCertificate" glib:get-type="g_tls_certificate_get_type" glib:type-struct="TlsCertificateClass"> + <doc xml:space="preserve">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).</doc> + <constructor name="new_from_file" c:identifier="g_tls_certificate_new_from_file" version="2.28" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new certificate, or %NULL on error</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">file containing a PEM-encoded certificate to import</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_files" c:identifier="g_tls_certificate_new_from_files" version="2.28" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new certificate, or %NULL on error</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <parameter name="cert_file" transfer-ownership="none"> + <doc xml:space="preserve">file containing one or more PEM-encoded + certificates to import</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="key_file" transfer-ownership="none"> + <doc xml:space="preserve">file containing a PEM-encoded private key + to import</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_pem" c:identifier="g_tls_certificate_new_from_pem" version="2.28" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new certificate, or %NULL if @data is invalid</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve">PEM-encoded certificate data</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of @data, or -1 if it's 0-terminated.</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </constructor> + <function name="list_new_from_file" c:identifier="g_tls_certificate_list_new_from_file" version="2.28" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a +#GList containing #GTlsCertificate objects. You must free the list +and its contents when you are done with it.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="TlsCertificate"/> + </type> + </return-value> + <parameters> + <parameter name="file" transfer-ownership="none"> + <doc xml:space="preserve">file containing PEM-encoded certificates to import</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <virtual-method name="verify" invoker="verify" version="2.28"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the appropriate #GTlsCertificateFlags</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </return-value> + <parameters> + <instance-parameter name="cert" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsCertificate</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </instance-parameter> + <parameter name="identity" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected peer identity</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="trusted_ca" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the certificate of a trusted authority</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_issuer" c:identifier="g_tls_certificate_get_issuer" version="2.28"> + <doc xml:space="preserve">Gets the #GTlsCertificate representing @cert's issuer, if known</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The certificate of @cert's issuer, +or %NULL if @cert is self-signed or signed with an unknown +certificate.</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <instance-parameter name="cert" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsCertificate</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_same" c:identifier="g_tls_certificate_is_same" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether the same or not</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="cert_one" transfer-ownership="none"> + <doc xml:space="preserve">first certificate to compare</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </instance-parameter> + <parameter name="cert_two" transfer-ownership="none"> + <doc xml:space="preserve">second certificate to compare</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + </parameters> + </method> + <method name="verify" c:identifier="g_tls_certificate_verify" version="2.28"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the appropriate #GTlsCertificateFlags</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </return-value> + <parameters> + <instance-parameter name="cert" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsCertificate</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </instance-parameter> + <parameter name="identity" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected peer identity</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="trusted_ca" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the certificate of a trusted authority</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + </parameters> + </method> + <property name="certificate" version="2.28" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The DER (binary) encoded representation of the certificate. +This property and the #GTlsCertificate:certificate-pem property +represent the same data, just in different forms.</doc> + <array name="GLib.ByteArray"> + <type name="guint8" c:type="guint8"/> + </array> + </property> + <property name="certificate-pem" version="2.28" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The PEM (ASCII) encoded representation of the certificate. +This property and the #GTlsCertificate:certificate +property represent the same data, just in different forms.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="issuer" version="2.28" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="TlsCertificate"/> + </property> + <property name="private-key" version="2.28" readable="0" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <array name="GLib.ByteArray"> + <type name="guint8" c:type="guint8"/> + </array> + </property> + <property name="private-key-pem" version="2.28" readable="0" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv"> + <type name="TlsCertificatePrivate" c:type="GTlsCertificatePrivate*"/> + </field> + </class> + <record name="TlsCertificateClass" c:type="GTlsCertificateClass" glib:is-gtype-struct-for="TlsCertificate"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="verify"> + <callback name="verify"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the appropriate #GTlsCertificateFlags</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </return-value> + <parameters> + <parameter name="cert" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsCertificate</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="identity" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected peer identity</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="trusted_ca" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the certificate of a trusted authority</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="8"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <bitfield name="TlsCertificateFlags" version="2.28" glib:type-name="GTlsCertificateFlags" glib:get-type="g_tls_certificate_flags_get_type" c:type="GTlsCertificateFlags"> + <doc xml:space="preserve">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).</doc> + <member name="unknown_ca" value="1" c:identifier="G_TLS_CERTIFICATE_UNKNOWN_CA" glib:nick="unknown-ca"> + <doc xml:space="preserve">The signing certificate authority is + not known.</doc> + </member> + <member name="bad_identity" value="2" c:identifier="G_TLS_CERTIFICATE_BAD_IDENTITY" glib:nick="bad-identity"> + <doc xml:space="preserve">The certificate does not match the + expected identity of the site that it was retrieved from.</doc> + </member> + <member name="not_activated" value="4" c:identifier="G_TLS_CERTIFICATE_NOT_ACTIVATED" glib:nick="not-activated"> + <doc xml:space="preserve">The certificate's activation time + is still in the future</doc> + </member> + <member name="expired" value="8" c:identifier="G_TLS_CERTIFICATE_EXPIRED" glib:nick="expired"> + <doc xml:space="preserve">The certificate has expired</doc> + </member> + <member name="revoked" value="16" c:identifier="G_TLS_CERTIFICATE_REVOKED" glib:nick="revoked"> + <doc xml:space="preserve">The certificate has been revoked + according to the #GTlsConnection's certificate revocation list.</doc> + </member> + <member name="insecure" value="32" c:identifier="G_TLS_CERTIFICATE_INSECURE" glib:nick="insecure"> + <doc xml:space="preserve">The certificate's algorithm is + considered insecure.</doc> + </member> + <member name="generic_error" value="64" c:identifier="G_TLS_CERTIFICATE_GENERIC_ERROR" glib:nick="generic-error"> + <doc xml:space="preserve">Some other error occurred validating + the certificate</doc> + </member> + <member name="validate_all" value="127" c:identifier="G_TLS_CERTIFICATE_VALIDATE_ALL" glib:nick="validate-all"> + <doc xml:space="preserve">the combination of all of the above + flags</doc> + </member> + </bitfield> + <record name="TlsCertificatePrivate" c:type="GTlsCertificatePrivate" disguised="1"/> + <enumeration name="TlsCertificateRequestFlags" version="2.40" glib:type-name="GTlsCertificateRequestFlags" glib:get-type="g_tls_certificate_request_flags_get_type" c:type="GTlsCertificateRequestFlags"> + <doc xml:space="preserve">Flags for g_tls_interaction_request_certificate(), +g_tls_interaction_request_certificate_async(), and +g_tls_interaction_invoke_request_certificate().</doc> + <member name="none" value="0" c:identifier="G_TLS_CERTIFICATE_REQUEST_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags</doc> + </member> + </enumeration> + <enumeration name="TlsChannelBindingError" version="2.66" glib:type-name="GTlsChannelBindingError" glib:get-type="g_tls_channel_binding_error_get_type" c:type="GTlsChannelBindingError" glib:error-domain="g-tls-channel-binding-error-quark"> + <doc xml:space="preserve">An error code used with %G_TLS_CHANNEL_BINDING_ERROR in a #GError to +indicate a TLS channel binding retrieval error.</doc> + <member name="not_implemented" value="0" c:identifier="G_TLS_CHANNEL_BINDING_ERROR_NOT_IMPLEMENTED" glib:nick="not-implemented"> + <doc xml:space="preserve">Either entire binding + retrieval facility or specific binding type is not implemented in the + TLS backend.</doc> + </member> + <member name="invalid_state" value="1" c:identifier="G_TLS_CHANNEL_BINDING_ERROR_INVALID_STATE" glib:nick="invalid-state"> + <doc xml:space="preserve">The handshake is not yet + complete on the connection which is a strong requirement for any existing + binding type.</doc> + </member> + <member name="not_available" value="2" c:identifier="G_TLS_CHANNEL_BINDING_ERROR_NOT_AVAILABLE" glib:nick="not-available"> + <doc xml:space="preserve">Handshake is complete but + binding data is not available. That normally indicates the TLS + implementation failed to provide the binding data. For example, some + implementations do not provide a peer certificate for resumed connections.</doc> + </member> + <member name="not_supported" value="3" c:identifier="G_TLS_CHANNEL_BINDING_ERROR_NOT_SUPPORTED" glib:nick="not-supported"> + <doc xml:space="preserve">Binding type is not supported + on the current connection. This error could be triggered when requesting + `tls-server-end-point` binding data for a certificate which has no hash + function or uses multiple hash functions.</doc> + </member> + <member name="general_error" value="4" c:identifier="G_TLS_CHANNEL_BINDING_ERROR_GENERAL_ERROR" glib:nick="general-error"> + <doc xml:space="preserve">Any other backend error + preventing binding data retrieval.</doc> + </member> + <function name="quark" c:identifier="g_tls_channel_binding_error_quark" version="2.66"> + <doc xml:space="preserve">Gets the TLS channel binding error quark.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </return-value> + </function> + </enumeration> + <enumeration name="TlsChannelBindingType" version="2.66" glib:type-name="GTlsChannelBindingType" glib:get-type="g_tls_channel_binding_type_get_type" c:type="GTlsChannelBindingType"> + <doc xml:space="preserve">The type of TLS channel binding data to retrieve from #GTlsConnection +or #GDtlsConnection, as documented by RFC 5929. The +[`tls-unique-for-telnet`](https://tools.ietf.org/html/rfc5929#section-5) +binding type is not currently implemented.</doc> + <member name="unique" value="0" c:identifier="G_TLS_CHANNEL_BINDING_TLS_UNIQUE" glib:nick="unique"> + <doc xml:space="preserve">[`tls-unique`](https://tools.ietf.org/html/rfc5929#section-3) binding + type</doc> + </member> + <member name="server_end_point" value="1" c:identifier="G_TLS_CHANNEL_BINDING_TLS_SERVER_END_POINT" glib:nick="server-end-point"> + <doc xml:space="preserve">[`tls-server-end-point`](https://tools.ietf.org/html/rfc5929#section-4) + binding type</doc> + </member> + </enumeration> + <interface name="TlsClientConnection" c:symbol-prefix="tls_client_connection" c:type="GTlsClientConnection" version="2.28" glib:type-name="GTlsClientConnection" glib:get-type="g_tls_client_connection_get_type" glib:type-struct="TlsClientConnectionInterface"> + <doc xml:space="preserve">#GTlsClientConnection is the client-side subclass of +#GTlsConnection, representing a client-side TLS connection.</doc> + <prerequisite name="TlsConnection"/> + <function name="new" c:identifier="g_tls_client_connection_new" version="2.28" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new +#GTlsClientConnection, or %NULL on error</doc> + <type name="TlsClientConnection" c:type="GIOStream*"/> + </return-value> + <parameters> + <parameter name="base_io_stream" transfer-ownership="none"> + <doc xml:space="preserve">the #GIOStream to wrap</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="server_identity" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected identity of the server</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + </parameters> + </function> + <virtual-method name="copy_session_state" invoker="copy_session_state" version="2.46"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsClientConnection</doc> + <type name="TlsClientConnection" c:type="GTlsClientConnection*"/> + </instance-parameter> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsClientConnection</doc> + <type name="TlsClientConnection" c:type="GTlsClientConnection*"/> + </parameter> + </parameters> + </virtual-method> + <method name="copy_session_state" c:identifier="g_tls_client_connection_copy_session_state" version="2.46"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsClientConnection</doc> + <type name="TlsClientConnection" c:type="GTlsClientConnection*"/> + </instance-parameter> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsClientConnection</doc> + <type name="TlsClientConnection" c:type="GTlsClientConnection*"/> + </parameter> + </parameters> + </method> + <method name="get_accepted_cas" c:identifier="g_tls_client_connection_get_accepted_cas" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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().</doc> + <type name="GLib.List" c:type="GList*"> + <array name="GLib.ByteArray"> + <type name="guint8" c:type="guint8"/> + </array> + </type> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsClientConnection</doc> + <type name="TlsClientConnection" c:type="GTlsClientConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_server_identity" c:identifier="g_tls_client_connection_get_server_identity" version="2.28"> + <doc xml:space="preserve">Gets @conn's expected server identity</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a #GSocketConnectable describing the +expected server identity, or %NULL if the expected identity is not +known.</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsClientConnection</doc> + <type name="TlsClientConnection" c:type="GTlsClientConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_use_ssl3" c:identifier="g_tls_client_connection_get_use_ssl3" version="2.28" deprecated="1" deprecated-version="2.56"> + <doc xml:space="preserve">SSL 3.0 is no longer supported. See +g_tls_client_connection_set_use_ssl3() for details.</doc> + <doc-deprecated xml:space="preserve">SSL 3.0 is insecure.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%FALSE</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsClientConnection</doc> + <type name="TlsClientConnection" c:type="GTlsClientConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_validation_flags" c:identifier="g_tls_client_connection_get_validation_flags" version="2.28"> + <doc xml:space="preserve">Gets @conn's validation flags</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the validation flags</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsClientConnection</doc> + <type name="TlsClientConnection" c:type="GTlsClientConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_server_identity" c:identifier="g_tls_client_connection_set_server_identity" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsClientConnection</doc> + <type name="TlsClientConnection" c:type="GTlsClientConnection*"/> + </instance-parameter> + <parameter name="identity" transfer-ownership="none"> + <doc xml:space="preserve">a #GSocketConnectable describing the expected server identity</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + </parameters> + </method> + <method name="set_use_ssl3" c:identifier="g_tls_client_connection_set_use_ssl3" version="2.28" deprecated="1" deprecated-version="2.56"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">SSL 3.0 is insecure.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsClientConnection</doc> + <type name="TlsClientConnection" c:type="GTlsClientConnection*"/> + </instance-parameter> + <parameter name="use_ssl3" transfer-ownership="none"> + <doc xml:space="preserve">a #gboolean, ignored</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_validation_flags" c:identifier="g_tls_client_connection_set_validation_flags" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsClientConnection</doc> + <type name="TlsClientConnection" c:type="GTlsClientConnection*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">the #GTlsCertificateFlags to use</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </parameter> + </parameters> + </method> + <property name="accepted-cas" version="2.28" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="GLib.List" c:type="gpointer"> + <type name="gpointer" c:type="gpointer"/> + </type> + </property> + <property name="server-identity" version="2.28" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="SocketConnectable"/> + </property> + <property name="use-ssl3" version="2.28" deprecated="1" deprecated-version="2.56" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">SSL 3.0 is no longer supported. See +g_tls_client_connection_set_use_ssl3() for details.</doc> + <doc-deprecated xml:space="preserve">SSL 3.0 is insecure.</doc-deprecated> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="validation-flags" version="2.28" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">What steps to perform when validating a certificate received from +a server. Server certificates that fail to validate in any of the +ways indicated here will be rejected unless the application +overrides the default via #GTlsConnection::accept-certificate.</doc> + <type name="TlsCertificateFlags"/> + </property> + </interface> + <record name="TlsClientConnectionInterface" c:type="GTlsClientConnectionInterface" glib:is-gtype-struct-for="TlsClientConnection" version="2.26"> + <doc xml:space="preserve">vtable for a #GTlsClientConnection implementation.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="copy_session_state"> + <callback name="copy_session_state"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsClientConnection</doc> + <type name="TlsClientConnection" c:type="GTlsClientConnection*"/> + </parameter> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsClientConnection</doc> + <type name="TlsClientConnection" c:type="GTlsClientConnection*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="TlsConnection" c:symbol-prefix="tls_connection" c:type="GTlsConnection" version="2.28" parent="IOStream" abstract="1" glib:type-name="GTlsConnection" glib:get-type="g_tls_connection_get_type" glib:type-struct="TlsConnectionClass"> + <doc xml:space="preserve">#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.</doc> + <virtual-method name="accept_certificate"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="peer_cert" transfer-ownership="none"> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="errors" transfer-ownership="none"> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_binding_data" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="type" transfer-ownership="none"> + <type name="TlsChannelBindingType" c:type="GTlsChannelBindingType"/> + </parameter> + <parameter name="data" transfer-ownership="none"> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="handshake" invoker="handshake" version="2.28" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">success or failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="handshake_async" invoker="handshake_async" version="2.28"> + <doc xml:space="preserve">Asynchronously performs a TLS handshake on @conn. See +g_tls_connection_handshake() for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call when the handshake is complete</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="handshake_finish" invoker="handshake_finish" version="2.28" throws="1"> + <doc xml:space="preserve">Finish an asynchronous TLS handshake operation. See +g_tls_connection_handshake() for more information.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on failure, in which +case @error will be set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <method name="emit_accept_certificate" c:identifier="g_tls_connection_emit_accept_certificate" version="2.28"> + <doc xml:space="preserve">Used by #GTlsConnection implementations to emit the +#GTlsConnection::accept-certificate signal.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if one of the signal handlers has returned + %TRUE to accept @peer_cert</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="peer_cert" transfer-ownership="none"> + <doc xml:space="preserve">the peer's #GTlsCertificate</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="errors" transfer-ownership="none"> + <doc xml:space="preserve">the problems with @peer_cert</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </parameter> + </parameters> + </method> + <method name="get_certificate" c:identifier="g_tls_connection_get_certificate" version="2.28"> + <doc xml:space="preserve">Gets @conn's certificate, as set by +g_tls_connection_set_certificate().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">@conn's certificate, or %NULL</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_channel_binding_data" c:identifier="g_tls_connection_get_channel_binding_data" version="2.66" throws="1"> + <doc xml:space="preserve">Query the TLS backend for TLS channel binding data of @type for @conn. + +This call retrieves TLS channel binding data as specified in RFC +[5056](https://tools.ietf.org/html/rfc5056), RFC +[5929](https://tools.ietf.org/html/rfc5929), and related RFCs. The +binding data is returned in @data. The @data is resized by the callee +using #GByteArray buffer management and will be freed when the @data +is destroyed by g_byte_array_unref(). If @data is %NULL, it will only +check whether TLS backend is able to fetch the data (e.g. whether @type +is supported by the TLS backend). It does not guarantee that the data +will be available though. That could happen if TLS connection does not +support @type or the binding data is not available yet due to additional +negotiation or input required.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">#GTlsChannelBindingType type of data to fetch</doc> + <type name="TlsChannelBindingType" c:type="GTlsChannelBindingType"/> + </parameter> + <parameter name="data" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1"> + <doc xml:space="preserve">#GByteArray is + filled with the binding data, or %NULL</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + </parameters> + </method> + <method name="get_database" c:identifier="g_tls_connection_get_database" version="2.30"> + <doc xml:space="preserve">Gets the certificate database that @conn uses to verify +peer certificates. See g_tls_connection_set_database().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the certificate database that @conn uses or %NULL</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_interaction" c:identifier="g_tls_connection_get_interaction" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The interaction object.</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a connection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_negotiated_protocol" c:identifier="g_tls_connection_get_negotiated_protocol" version="2.60"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the negotiated protocol, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_peer_certificate" c:identifier="g_tls_connection_get_peer_certificate" version="2.28"> + <doc xml:space="preserve">Gets @conn's peer's certificate after the handshake has completed +or failed. (It is not set during the emission of +#GTlsConnection::accept-certificate.)</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">@conn's peer's certificate, or %NULL</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_peer_certificate_errors" c:identifier="g_tls_connection_get_peer_certificate_errors" version="2.28"> + <doc xml:space="preserve">Gets the errors associated with validating @conn's peer's +certificate, after the handshake has completed or failed. (It is +not set during the emission of #GTlsConnection::accept-certificate.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">@conn's peer's certificate errors</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_rehandshake_mode" c:identifier="g_tls_connection_get_rehandshake_mode" version="2.28" deprecated="1" deprecated-version="2.60."> + <doc xml:space="preserve">Gets @conn rehandshaking mode. See +g_tls_connection_set_rehandshake_mode() for details.</doc> + <doc-deprecated xml:space="preserve">Changing the rehandshake mode is no longer + required for compatibility. Also, rehandshaking has been removed + from the TLS protocol in TLS 1.3.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%G_TLS_REHANDSHAKE_SAFELY</doc> + <type name="TlsRehandshakeMode" c:type="GTlsRehandshakeMode"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_require_close_notify" c:identifier="g_tls_connection_get_require_close_notify" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @conn requires a proper TLS close +notification.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_use_system_certdb" c:identifier="g_tls_connection_get_use_system_certdb" deprecated="1" deprecated-version="2.30"> + <doc xml:space="preserve">Gets whether @conn uses the system certificate database to verify +peer certificates. See g_tls_connection_set_use_system_certdb().</doc> + <doc-deprecated xml:space="preserve">Use g_tls_connection_get_database() instead</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">whether @conn uses the system certificate database</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + </parameters> + </method> + <method name="handshake" c:identifier="g_tls_connection_handshake" version="2.28" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">success or failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="handshake_async" c:identifier="g_tls_connection_handshake_async" version="2.28"> + <doc xml:space="preserve">Asynchronously performs a TLS handshake on @conn. See +g_tls_connection_handshake() for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">callback to call when the handshake is complete</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="handshake_finish" c:identifier="g_tls_connection_handshake_finish" version="2.28" throws="1"> + <doc xml:space="preserve">Finish an asynchronous TLS handshake operation. See +g_tls_connection_handshake() for more information.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on failure, in which +case @error will be set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="set_advertised_protocols" c:identifier="g_tls_connection_set_advertised_protocols" version="2.60"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="protocols" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a %NULL-terminated + array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL</doc> + <array c:type="const gchar* const*"> + <type name="utf8" c:type="gchar*"/> + </array> + </parameter> + </parameters> + </method> + <method name="set_certificate" c:identifier="g_tls_connection_set_certificate" version="2.28"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="certificate" transfer-ownership="none"> + <doc xml:space="preserve">the certificate to use for @conn</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + </parameters> + </method> + <method name="set_database" c:identifier="g_tls_connection_set_database" version="2.30"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="database" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </parameter> + </parameters> + </method> + <method name="set_interaction" c:identifier="g_tls_connection_set_interaction" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a connection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an interaction object, or %NULL</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + </parameters> + </method> + <method name="set_rehandshake_mode" c:identifier="g_tls_connection_set_rehandshake_mode" version="2.28" deprecated="1" deprecated-version="2.60."> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Changing the rehandshake mode is no longer + required for compatibility. Also, rehandshaking has been removed + from the TLS protocol in TLS 1.3.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve">the rehandshaking mode</doc> + <type name="TlsRehandshakeMode" c:type="GTlsRehandshakeMode"/> + </parameter> + </parameters> + </method> + <method name="set_require_close_notify" c:identifier="g_tls_connection_set_require_close_notify" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="require_close_notify" transfer-ownership="none"> + <doc xml:space="preserve">whether or not to require close notification</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_use_system_certdb" c:identifier="g_tls_connection_set_use_system_certdb" deprecated="1" deprecated-version="2.30"> + <doc xml:space="preserve">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).</doc> + <doc-deprecated xml:space="preserve">Use g_tls_connection_set_database() instead</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </instance-parameter> + <parameter name="use_system_certdb" transfer-ownership="none"> + <doc xml:space="preserve">whether to use the system certificate database</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <property name="advertised-protocols" version="2.60" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">The list of application-layer protocols that the connection +advertises that it is willing to speak. See +g_tls_connection_set_advertised_protocols().</doc> + <array> + <type name="utf8"/> + </array> + </property> + <property name="base-io-stream" version="2.28" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="IOStream"/> + </property> + <property name="certificate" version="2.28" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">The connection's certificate; see +g_tls_connection_set_certificate().</doc> + <type name="TlsCertificate"/> + </property> + <property name="database" version="2.30" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">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().</doc> + <type name="TlsDatabase"/> + </property> + <property name="interaction" version="2.30" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="TlsInteraction"/> + </property> + <property name="negotiated-protocol" version="2.60" transfer-ownership="none"> + <doc xml:space="preserve">The application-layer protocol negotiated during the TLS +handshake. See g_tls_connection_get_negotiated_protocol().</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="peer-certificate" version="2.28" transfer-ownership="none"> + <doc xml:space="preserve">The connection's peer's certificate, after the TLS handshake has +completed or failed. 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.)</doc> + <type name="TlsCertificate"/> + </property> + <property name="peer-certificate-errors" version="2.28" transfer-ownership="none"> + <doc xml:space="preserve">The errors noticed 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.</doc> + <type name="TlsCertificateFlags"/> + </property> + <property name="rehandshake-mode" version="2.28" deprecated="1" deprecated-version="2.60" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">The rehandshaking mode. See +g_tls_connection_set_rehandshake_mode().</doc> + <doc-deprecated xml:space="preserve">The rehandshake mode is ignored.</doc-deprecated> + <type name="TlsRehandshakeMode"/> + </property> + <property name="require-close-notify" version="2.28" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">Whether or not proper TLS close notification is required. +See g_tls_connection_set_require_close_notify().</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="use-system-certdb" deprecated="1" deprecated-version="2.30" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">Whether or not the system certificate database will be used to +verify peer certificates. See +g_tls_connection_set_use_system_certdb().</doc> + <doc-deprecated xml:space="preserve">Use GTlsConnection:database instead</doc-deprecated> + <type name="gboolean" c:type="gboolean"/> + </property> + <field name="parent_instance"> + <type name="IOStream" c:type="GIOStream"/> + </field> + <field name="priv"> + <type name="TlsConnectionPrivate" c:type="GTlsConnectionPrivate*"/> + </field> + <glib:signal name="accept-certificate" when="last" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%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.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="peer_cert" transfer-ownership="none"> + <doc xml:space="preserve">the peer's #GTlsCertificate</doc> + <type name="TlsCertificate"/> + </parameter> + <parameter name="errors" transfer-ownership="none"> + <doc xml:space="preserve">the problems with @peer_cert.</doc> + <type name="TlsCertificateFlags"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="TlsConnectionClass" c:type="GTlsConnectionClass" glib:is-gtype-struct-for="TlsConnection"> + <field name="parent_class"> + <type name="IOStreamClass" c:type="GIOStreamClass"/> + </field> + <field name="accept_certificate"> + <callback name="accept_certificate"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </parameter> + <parameter name="peer_cert" transfer-ownership="none"> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="errors" transfer-ownership="none"> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </parameter> + </parameters> + </callback> + </field> + <field name="handshake"> + <callback name="handshake" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">success or failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="handshake_async"> + <callback name="handshake_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the request</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">callback to call when the handshake is complete</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="handshake_finish"> + <callback name="handshake_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on failure, in which +case @error will be set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="conn" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_binding_data"> + <callback name="get_binding_data" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="conn" transfer-ownership="none"> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <type name="TlsChannelBindingType" c:type="GTlsChannelBindingType"/> + </parameter> + <parameter name="data" transfer-ownership="none"> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + </parameters> + </callback> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="7"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <record name="TlsConnectionPrivate" c:type="GTlsConnectionPrivate" disguised="1"/> + <class name="TlsDatabase" c:symbol-prefix="tls_database" c:type="GTlsDatabase" version="2.30" parent="GObject.Object" abstract="1" glib:type-name="GTlsDatabase" glib:get-type="g_tls_database_get_type" glib:type-struct="TlsDatabaseClass"> + <doc xml:space="preserve">#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.</doc> + <virtual-method name="create_certificate_handle" invoker="create_certificate_handle" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly allocated string containing the +handle.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="certificate" transfer-ownership="none"> + <doc xml:space="preserve">certificate for which to create a handle.</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_certificate_for_handle" invoker="lookup_certificate_for_handle" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly allocated +#GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="handle" transfer-ownership="none"> + <doc xml:space="preserve">a certificate handle</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags which affect the lookup.</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_certificate_for_handle_async" invoker="lookup_certificate_for_handle_async" version="2.30"> + <doc xml:space="preserve">Asynchronously look up a certificate by its handle in the database. See +g_tls_database_lookup_certificate_for_handle() for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="handle" transfer-ownership="none"> + <doc xml:space="preserve">a certificate handle</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags which affect the lookup.</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the operation completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_certificate_for_handle_finish" invoker="lookup_certificate_for_handle_finish" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated #GTlsCertificate object. +Use g_object_unref() to release the certificate.</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_certificate_issuer" invoker="lookup_certificate_issuer" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated issuer #GTlsCertificate, +or %NULL. Use g_object_unref() to release the certificate.</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="certificate" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsCertificate</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags which affect the lookup operation</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_certificate_issuer_async" invoker="lookup_certificate_issuer_async" version="2.30"> + <doc xml:space="preserve">Asynchronously look up the issuer of @certificate in the database. See +g_tls_database_lookup_certificate_issuer() for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="certificate" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsCertificate</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags which affect the lookup operation</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the operation completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_certificate_issuer_finish" invoker="lookup_certificate_issuer_finish" version="2.30" throws="1"> + <doc xml:space="preserve">Finish an asynchronous lookup issuer operation. See +g_tls_database_lookup_certificate_issuer() for more information.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated issuer #GTlsCertificate, +or %NULL. Use g_object_unref() to release the certificate.</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_certificates_issued_by" invoker="lookup_certificates_issued_by" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated list of #GTlsCertificate +objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="TlsCertificate"/> + </type> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="issuer_raw_dn" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray which holds the DER encoded issuer DN.</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags which affect the lookup operation.</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_certificates_issued_by_async" invoker="lookup_certificates_issued_by_async" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="issuer_raw_dn" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray which holds the DER encoded issuer DN.</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags which affect the lookup operation.</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the operation completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="lookup_certificates_issued_by_finish" invoker="lookup_certificates_issued_by_finish" version="2.30" throws="1"> + <doc xml:space="preserve">Finish an asynchronous lookup of certificates. See +g_tls_database_lookup_certificates_issued_by() for more information.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated list of #GTlsCertificate +objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="TlsCertificate"/> + </type> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="verify_chain" invoker="verify_chain" version="2.30" throws="1"> + <doc xml:space="preserve">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 ensure the server certificate is valid for +the expected peer identity. If the identity does not match the +certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the +return value. If @identity is %NULL, that bit will never be set in +the return value. The peer identity may also be used to check for +pinned certificates (trust exceptions) in the database. These may +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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the appropriate #GTlsCertificateFlags which represents the +result of verification.</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="chain" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsCertificate chain</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="purpose" transfer-ownership="none"> + <doc xml:space="preserve">the purpose that this certificate chain will be used for.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="identity" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected peer identity</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">additional verify flags</doc> + <type name="TlsDatabaseVerifyFlags" c:type="GTlsDatabaseVerifyFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="verify_chain_async" invoker="verify_chain_async" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="chain" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsCertificate chain</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="purpose" transfer-ownership="none"> + <doc xml:space="preserve">the purpose that this certificate chain will be used for.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="identity" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected peer identity</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">additional verify flags</doc> + <type name="TlsDatabaseVerifyFlags" c:type="GTlsDatabaseVerifyFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="7"> + <doc xml:space="preserve">callback to call when the operation completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="7"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="verify_chain_finish" invoker="verify_chain_finish" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the appropriate #GTlsCertificateFlags which represents the +result of verification.</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <method name="create_certificate_handle" c:identifier="g_tls_database_create_certificate_handle" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly allocated string containing the +handle.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="certificate" transfer-ownership="none"> + <doc xml:space="preserve">certificate for which to create a handle.</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + </parameters> + </method> + <method name="lookup_certificate_for_handle" c:identifier="g_tls_database_lookup_certificate_for_handle" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly allocated +#GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="handle" transfer-ownership="none"> + <doc xml:space="preserve">a certificate handle</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags which affect the lookup.</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="lookup_certificate_for_handle_async" c:identifier="g_tls_database_lookup_certificate_for_handle_async" version="2.30"> + <doc xml:space="preserve">Asynchronously look up a certificate by its handle in the database. See +g_tls_database_lookup_certificate_for_handle() for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="handle" transfer-ownership="none"> + <doc xml:space="preserve">a certificate handle</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags which affect the lookup.</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the operation completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="lookup_certificate_for_handle_finish" c:identifier="g_tls_database_lookup_certificate_for_handle_finish" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated #GTlsCertificate object. +Use g_object_unref() to release the certificate.</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="lookup_certificate_issuer" c:identifier="g_tls_database_lookup_certificate_issuer" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated issuer #GTlsCertificate, +or %NULL. Use g_object_unref() to release the certificate.</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="certificate" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsCertificate</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags which affect the lookup operation</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="lookup_certificate_issuer_async" c:identifier="g_tls_database_lookup_certificate_issuer_async" version="2.30"> + <doc xml:space="preserve">Asynchronously look up the issuer of @certificate in the database. See +g_tls_database_lookup_certificate_issuer() for more information.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="certificate" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsCertificate</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags which affect the lookup operation</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the operation completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="lookup_certificate_issuer_finish" c:identifier="g_tls_database_lookup_certificate_issuer_finish" version="2.30" throws="1"> + <doc xml:space="preserve">Finish an asynchronous lookup issuer operation. See +g_tls_database_lookup_certificate_issuer() for more information.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated issuer #GTlsCertificate, +or %NULL. Use g_object_unref() to release the certificate.</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="lookup_certificates_issued_by" c:identifier="g_tls_database_lookup_certificates_issued_by" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated list of #GTlsCertificate +objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="TlsCertificate"/> + </type> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="issuer_raw_dn" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray which holds the DER encoded issuer DN.</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags which affect the lookup operation.</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="lookup_certificates_issued_by_async" c:identifier="g_tls_database_lookup_certificates_issued_by_async" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="issuer_raw_dn" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray which holds the DER encoded issuer DN.</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags which affect the lookup operation.</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">callback to call when the operation completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="lookup_certificates_issued_by_finish" c:identifier="g_tls_database_lookup_certificates_issued_by_finish" version="2.30" throws="1"> + <doc xml:space="preserve">Finish an asynchronous lookup of certificates. See +g_tls_database_lookup_certificates_issued_by() for more information.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated list of #GTlsCertificate +objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="TlsCertificate"/> + </type> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="verify_chain" c:identifier="g_tls_database_verify_chain" version="2.30" throws="1"> + <doc xml:space="preserve">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 ensure the server certificate is valid for +the expected peer identity. If the identity does not match the +certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the +return value. If @identity is %NULL, that bit will never be set in +the return value. The peer identity may also be used to check for +pinned certificates (trust exceptions) in the database. These may +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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the appropriate #GTlsCertificateFlags which represents the +result of verification.</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="chain" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsCertificate chain</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="purpose" transfer-ownership="none"> + <doc xml:space="preserve">the purpose that this certificate chain will be used for.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="identity" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected peer identity</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">additional verify flags</doc> + <type name="TlsDatabaseVerifyFlags" c:type="GTlsDatabaseVerifyFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="verify_chain_async" c:identifier="g_tls_database_verify_chain_async" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="chain" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsCertificate chain</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="purpose" transfer-ownership="none"> + <doc xml:space="preserve">the purpose that this certificate chain will be used for.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="identity" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected peer identity</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">additional verify flags</doc> + <type name="TlsDatabaseVerifyFlags" c:type="GTlsDatabaseVerifyFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="7"> + <doc xml:space="preserve">callback to call when the operation completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="verify_chain_finish" c:identifier="g_tls_database_verify_chain_finish" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the appropriate #GTlsCertificateFlags which represents the +result of verification.</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv"> + <type name="TlsDatabasePrivate" c:type="GTlsDatabasePrivate*"/> + </field> + </class> + <record name="TlsDatabaseClass" c:type="GTlsDatabaseClass" glib:is-gtype-struct-for="TlsDatabase" version="2.30"> + <doc xml:space="preserve">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.</doc> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="verify_chain"> + <callback name="verify_chain" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the appropriate #GTlsCertificateFlags which represents the +result of verification.</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </parameter> + <parameter name="chain" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsCertificate chain</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="purpose" transfer-ownership="none"> + <doc xml:space="preserve">the purpose that this certificate chain will be used for.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="identity" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected peer identity</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">additional verify flags</doc> + <type name="TlsDatabaseVerifyFlags" c:type="GTlsDatabaseVerifyFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="verify_chain_async"> + <callback name="verify_chain_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </parameter> + <parameter name="chain" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsCertificate chain</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="purpose" transfer-ownership="none"> + <doc xml:space="preserve">the purpose that this certificate chain will be used for.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="identity" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected peer identity</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">additional verify flags</doc> + <type name="TlsDatabaseVerifyFlags" c:type="GTlsDatabaseVerifyFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="8"> + <doc xml:space="preserve">callback to call when the operation completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="8"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="verify_chain_finish"> + <callback name="verify_chain_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the appropriate #GTlsCertificateFlags which represents the +result of verification.</doc> + <type name="TlsCertificateFlags" c:type="GTlsCertificateFlags"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="create_certificate_handle"> + <callback name="create_certificate_handle"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly allocated string containing the +handle.</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </parameter> + <parameter name="certificate" transfer-ownership="none"> + <doc xml:space="preserve">certificate for which to create a handle.</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_certificate_for_handle"> + <callback name="lookup_certificate_for_handle" throws="1"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly allocated +#GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </parameter> + <parameter name="handle" transfer-ownership="none"> + <doc xml:space="preserve">a certificate handle</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags which affect the lookup.</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_certificate_for_handle_async"> + <callback name="lookup_certificate_for_handle_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </parameter> + <parameter name="handle" transfer-ownership="none"> + <doc xml:space="preserve">a certificate handle</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags which affect the lookup.</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">callback to call when the operation completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_certificate_for_handle_finish"> + <callback name="lookup_certificate_for_handle_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated #GTlsCertificate object. +Use g_object_unref() to release the certificate.</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_certificate_issuer"> + <callback name="lookup_certificate_issuer" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated issuer #GTlsCertificate, +or %NULL. Use g_object_unref() to release the certificate.</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </parameter> + <parameter name="certificate" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsCertificate</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags which affect the lookup operation</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_certificate_issuer_async"> + <callback name="lookup_certificate_issuer_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </parameter> + <parameter name="certificate" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsCertificate</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags which affect the lookup operation</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">callback to call when the operation completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_certificate_issuer_finish"> + <callback name="lookup_certificate_issuer_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated issuer #GTlsCertificate, +or %NULL. Use g_object_unref() to release the certificate.</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_certificates_issued_by"> + <callback name="lookup_certificates_issued_by" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated list of #GTlsCertificate +objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="TlsCertificate"/> + </type> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </parameter> + <parameter name="issuer_raw_dn" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray which holds the DER encoded issuer DN.</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags which affect the lookup operation.</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_certificates_issued_by_async"> + <callback name="lookup_certificates_issued_by_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </parameter> + <parameter name="issuer_raw_dn" transfer-ownership="none"> + <doc xml:space="preserve">a #GByteArray which holds the DER encoded issuer DN.</doc> + <array name="GLib.ByteArray" c:type="GByteArray*"> + <type name="guint8" c:type="guint8"/> + </array> + </parameter> + <parameter name="interaction" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">used to interact with the user if necessary</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags which affect the lookup operation.</doc> + <type name="TlsDatabaseLookupFlags" c:type="GTlsDatabaseLookupFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable, or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">callback to call when the operation completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="6"> + <doc xml:space="preserve">the data to pass to the callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="lookup_certificates_issued_by_finish"> + <callback name="lookup_certificates_issued_by_finish" throws="1"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated list of #GTlsCertificate +objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="TlsCertificate"/> + </type> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsDatabase</doc> + <type name="TlsDatabase" c:type="GTlsDatabase*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="16"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <enumeration name="TlsDatabaseLookupFlags" version="2.30" glib:type-name="GTlsDatabaseLookupFlags" glib:get-type="g_tls_database_lookup_flags_get_type" c:type="GTlsDatabaseLookupFlags"> + <doc xml:space="preserve">Flags for g_tls_database_lookup_certificate_for_handle(), +g_tls_database_lookup_certificate_issuer(), +and g_tls_database_lookup_certificates_issued_by().</doc> + <member name="none" value="0" c:identifier="G_TLS_DATABASE_LOOKUP_NONE" glib:nick="none"> + <doc xml:space="preserve">No lookup flags</doc> + </member> + <member name="keypair" value="1" c:identifier="G_TLS_DATABASE_LOOKUP_KEYPAIR" glib:nick="keypair"> + <doc xml:space="preserve">Restrict lookup to certificates that have + a private key.</doc> + </member> + </enumeration> + <record name="TlsDatabasePrivate" c:type="GTlsDatabasePrivate" disguised="1"/> + <bitfield name="TlsDatabaseVerifyFlags" version="2.30" glib:type-name="GTlsDatabaseVerifyFlags" glib:get-type="g_tls_database_verify_flags_get_type" c:type="GTlsDatabaseVerifyFlags"> + <doc xml:space="preserve">Flags for g_tls_database_verify_chain().</doc> + <member name="none" value="0" c:identifier="G_TLS_DATABASE_VERIFY_NONE" glib:nick="none"> + <doc xml:space="preserve">No verification flags</doc> + </member> + </bitfield> + <enumeration name="TlsError" version="2.28" glib:type-name="GTlsError" glib:get-type="g_tls_error_get_type" c:type="GTlsError" glib:error-domain="g-tls-error-quark"> + <doc xml:space="preserve">An error code used with %G_TLS_ERROR in a #GError returned from a +TLS-related routine.</doc> + <member name="unavailable" value="0" c:identifier="G_TLS_ERROR_UNAVAILABLE" glib:nick="unavailable"> + <doc xml:space="preserve">No TLS provider is available</doc> + </member> + <member name="misc" value="1" c:identifier="G_TLS_ERROR_MISC" glib:nick="misc"> + <doc xml:space="preserve">Miscellaneous TLS error</doc> + </member> + <member name="bad_certificate" value="2" c:identifier="G_TLS_ERROR_BAD_CERTIFICATE" glib:nick="bad-certificate"> + <doc xml:space="preserve">The certificate presented could not + be parsed or failed validation.</doc> + </member> + <member name="not_tls" value="3" c:identifier="G_TLS_ERROR_NOT_TLS" glib:nick="not-tls"> + <doc xml:space="preserve">The TLS handshake failed because the + peer does not seem to be a TLS server.</doc> + </member> + <member name="handshake" value="4" c:identifier="G_TLS_ERROR_HANDSHAKE" glib:nick="handshake"> + <doc xml:space="preserve">The TLS handshake failed because the + peer's certificate was not acceptable.</doc> + </member> + <member name="certificate_required" value="5" c:identifier="G_TLS_ERROR_CERTIFICATE_REQUIRED" glib:nick="certificate-required"> + <doc xml:space="preserve">The TLS handshake failed because + the server requested a client-side certificate, but none was + provided. See g_tls_connection_set_certificate().</doc> + </member> + <member name="eof" value="6" c:identifier="G_TLS_ERROR_EOF" glib:nick="eof"> + <doc xml:space="preserve">The TLS connection was closed without proper + notice, which may indicate an attack. See + g_tls_connection_set_require_close_notify().</doc> + </member> + <member name="inappropriate_fallback" value="7" c:identifier="G_TLS_ERROR_INAPPROPRIATE_FALLBACK" glib:nick="inappropriate-fallback"> + <doc xml:space="preserve">The TLS handshake failed + because the client sent the fallback SCSV, indicating a protocol + downgrade attack. Since: 2.60</doc> + </member> + <function name="quark" c:identifier="g_tls_error_quark" version="2.28"> + <doc xml:space="preserve">Gets the TLS error quark.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </return-value> + </function> + </enumeration> + <interface name="TlsFileDatabase" c:symbol-prefix="tls_file_database" c:type="GTlsFileDatabase" version="2.30" glib:type-name="GTlsFileDatabase" glib:get-type="g_tls_file_database_get_type" glib:type-struct="TlsFileDatabaseInterface"> + <doc xml:space="preserve">#GTlsFileDatabase is implemented by #GTlsDatabase objects which load +their certificate information from a file. It is an interface which +TLS library specific subtypes implement.</doc> + <prerequisite name="TlsDatabase"/> + <function name="new" c:identifier="g_tls_file_database_new" version="2.30" throws="1"> + <doc xml:space="preserve">Creates a new #GTlsFileDatabase which uses anchor certificate authorities +in @anchors to verify certificate chains. + +The certificates in @anchors must be PEM encoded.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new +#GTlsFileDatabase, or %NULL on error</doc> + <type name="TlsFileDatabase" c:type="GTlsDatabase*"/> + </return-value> + <parameters> + <parameter name="anchors" transfer-ownership="none"> + <doc xml:space="preserve">filename of anchor certificate authorities.</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <property name="anchors" version="2.30" writable="1" construct="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + </interface> + <record name="TlsFileDatabaseInterface" c:type="GTlsFileDatabaseInterface" glib:is-gtype-struct-for="TlsFileDatabase"> + <doc xml:space="preserve">Provides an interface for #GTlsFileDatabase implementations.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="8"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <class name="TlsInteraction" c:symbol-prefix="tls_interaction" c:type="GTlsInteraction" version="2.30" parent="GObject.Object" glib:type-name="GTlsInteraction" glib:get-type="g_tls_interaction_get_type" glib:type-struct="TlsInteractionClass"> + <doc xml:space="preserve">#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.</doc> + <virtual-method name="ask_password" invoker="ask_password" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The status of the ask password interaction.</doc> + <type name="TlsInteractionResult" c:type="GTlsInteractionResult"/> + </return-value> + <parameters> + <instance-parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </instance-parameter> + <parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GCancellable cancellation object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="ask_password_async" invoker="ask_password_async" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </instance-parameter> + <parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GCancellable cancellation object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">will be called when the interaction completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">data to pass to the @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="ask_password_finish" invoker="ask_password_finish" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The status of the ask password interaction.</doc> + <type name="TlsInteractionResult" c:type="GTlsInteractionResult"/> + </return-value> + <parameters> + <instance-parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to the callback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="request_certificate" invoker="request_certificate" version="2.40" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The status of the request certificate interaction.</doc> + <type name="TlsInteractionResult" c:type="GTlsInteractionResult"/> + </return-value> + <parameters> + <instance-parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection object</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags providing more information about the request</doc> + <type name="TlsCertificateRequestFlags" c:type="GTlsCertificateRequestFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GCancellable cancellation object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="request_certificate_async" invoker="request_certificate_async" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection object</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags providing more information about the request</doc> + <type name="TlsCertificateRequestFlags" c:type="GTlsCertificateRequestFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GCancellable cancellation object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">will be called when the interaction completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">data to pass to the @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="request_certificate_finish" invoker="request_certificate_finish" version="2.40" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The status of the request certificate interaction.</doc> + <type name="TlsInteractionResult" c:type="GTlsInteractionResult"/> + </return-value> + <parameters> + <instance-parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to the callback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <method name="ask_password" c:identifier="g_tls_interaction_ask_password" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The status of the ask password interaction.</doc> + <type name="TlsInteractionResult" c:type="GTlsInteractionResult"/> + </return-value> + <parameters> + <instance-parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </instance-parameter> + <parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GCancellable cancellation object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="ask_password_async" c:identifier="g_tls_interaction_ask_password_async" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </instance-parameter> + <parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GCancellable cancellation object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">will be called when the interaction completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to the @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="ask_password_finish" c:identifier="g_tls_interaction_ask_password_finish" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The status of the ask password interaction.</doc> + <type name="TlsInteractionResult" c:type="GTlsInteractionResult"/> + </return-value> + <parameters> + <instance-parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to the callback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="invoke_ask_password" c:identifier="g_tls_interaction_invoke_ask_password" version="2.30" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The status of the ask password interaction.</doc> + <type name="TlsInteractionResult" c:type="GTlsInteractionResult"/> + </return-value> + <parameters> + <instance-parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </instance-parameter> + <parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GCancellable cancellation object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="invoke_request_certificate" c:identifier="g_tls_interaction_invoke_request_certificate" version="2.40" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The status of the certificate request interaction.</doc> + <type name="TlsInteractionResult" c:type="GTlsInteractionResult"/> + </return-value> + <parameters> + <instance-parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection object</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags providing more information about the request</doc> + <type name="TlsCertificateRequestFlags" c:type="GTlsCertificateRequestFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GCancellable cancellation object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="request_certificate" c:identifier="g_tls_interaction_request_certificate" version="2.40" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The status of the request certificate interaction.</doc> + <type name="TlsInteractionResult" c:type="GTlsInteractionResult"/> + </return-value> + <parameters> + <instance-parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection object</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags providing more information about the request</doc> + <type name="TlsCertificateRequestFlags" c:type="GTlsCertificateRequestFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GCancellable cancellation object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="request_certificate_async" c:identifier="g_tls_interaction_request_certificate_async" version="2.40"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </instance-parameter> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection object</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags providing more information about the request</doc> + <type name="TlsCertificateRequestFlags" c:type="GTlsCertificateRequestFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GCancellable cancellation object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">will be called when the interaction completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to the @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="request_certificate_finish" c:identifier="g_tls_interaction_request_certificate_finish" version="2.40" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The status of the request certificate interaction.</doc> + <type name="TlsInteractionResult" c:type="GTlsInteractionResult"/> + </return-value> + <parameters> + <instance-parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to the callback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <field name="parent_instance" readable="0" private="1"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="TlsInteractionPrivate" c:type="GTlsInteractionPrivate*"/> + </field> + </class> + <record name="TlsInteractionClass" c:type="GTlsInteractionClass" glib:is-gtype-struct-for="TlsInteraction" version="2.30"> + <doc xml:space="preserve">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.</doc> + <field name="parent_class" readable="0" private="1"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="ask_password"> + <callback name="ask_password" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The status of the ask password interaction.</doc> + <type name="TlsInteractionResult" c:type="GTlsInteractionResult"/> + </return-value> + <parameters> + <parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GCancellable cancellation object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="ask_password_async"> + <callback name="ask_password_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GCancellable cancellation object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">will be called when the interaction completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">data to pass to the @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="ask_password_finish"> + <callback name="ask_password_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The status of the ask password interaction.</doc> + <type name="TlsInteractionResult" c:type="GTlsInteractionResult"/> + </return-value> + <parameters> + <parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to the callback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="request_certificate"> + <callback name="request_certificate" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The status of the request certificate interaction.</doc> + <type name="TlsInteractionResult" c:type="GTlsInteractionResult"/> + </return-value> + <parameters> + <parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection object</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags providing more information about the request</doc> + <type name="TlsCertificateRequestFlags" c:type="GTlsCertificateRequestFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GCancellable cancellation object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="request_certificate_async"> + <callback name="request_certificate_async"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsConnection object</doc> + <type name="TlsConnection" c:type="GTlsConnection*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags providing more information about the request</doc> + <type name="TlsCertificateRequestFlags" c:type="GTlsCertificateRequestFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GCancellable cancellation object</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">will be called when the interaction completes</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">data to pass to the @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="request_certificate_finish"> + <callback name="request_certificate_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The status of the request certificate interaction.</doc> + <type name="TlsInteractionResult" c:type="GTlsInteractionResult"/> + </return-value> + <parameters> + <parameter name="interaction" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsInteraction object</doc> + <type name="TlsInteraction" c:type="GTlsInteraction*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">the result passed to the callback</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="21"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <record name="TlsInteractionPrivate" c:type="GTlsInteractionPrivate" disguised="1"/> + <enumeration name="TlsInteractionResult" version="2.30" glib:type-name="GTlsInteractionResult" glib:get-type="g_tls_interaction_result_get_type" c:type="GTlsInteractionResult"> + <doc xml:space="preserve">#GTlsInteractionResult is returned by various functions in #GTlsInteraction +when finishing an interaction request.</doc> + <member name="unhandled" value="0" c:identifier="G_TLS_INTERACTION_UNHANDLED" glib:nick="unhandled"> + <doc xml:space="preserve">The interaction was unhandled (i.e. not + implemented).</doc> + </member> + <member name="handled" value="1" c:identifier="G_TLS_INTERACTION_HANDLED" glib:nick="handled"> + <doc xml:space="preserve">The interaction completed, and resulting data + is available.</doc> + </member> + <member name="failed" value="2" c:identifier="G_TLS_INTERACTION_FAILED" glib:nick="failed"> + <doc xml:space="preserve">The interaction has failed, or was cancelled. + and the operation should be aborted.</doc> + </member> + </enumeration> + <class name="TlsPassword" c:symbol-prefix="tls_password" c:type="GTlsPassword" version="2.30" parent="GObject.Object" glib:type-name="GTlsPassword" glib:get-type="g_tls_password_get_type" glib:type-struct="TlsPasswordClass"> + <doc xml:space="preserve">Holds a password used in TLS.</doc> + <constructor name="new" c:identifier="g_tls_password_new"> + <doc xml:space="preserve">Create a new #GTlsPassword object.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">The newly allocated password object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </return-value> + <parameters> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">the password flags</doc> + <type name="TlsPasswordFlags" c:type="GTlsPasswordFlags"/> + </parameter> + <parameter name="description" transfer-ownership="none"> + <doc xml:space="preserve">description of what the password is for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <virtual-method name="get_default_warning"> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="password" transfer-ownership="none"> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_value" invoker="get_value" version="2.30"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The password value (owned by the password object).</doc> + <type name="guint8" c:type="const guchar*"/> + </return-value> + <parameters> + <instance-parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </instance-parameter> + <parameter name="length" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">location to place the length of the password.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="set_value" invoker="set_value_full" version="2.30"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value for the password</doc> + <array length="1" zero-terminated="0" c:type="guchar*"> + <type name="guint8" c:type="guchar"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of the password, or -1</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a function to use to free the password.</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_description" c:identifier="g_tls_password_get_description" version="2.30"> + <doc xml:space="preserve">Get a description string about what the password will be used for.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The description of the password.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_flags" c:identifier="g_tls_password_get_flags" version="2.30"> + <doc xml:space="preserve">Get flags about the password.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The flags about the password.</doc> + <type name="TlsPasswordFlags" c:type="GTlsPasswordFlags"/> + </return-value> + <parameters> + <instance-parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_value" c:identifier="g_tls_password_get_value" version="2.30"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The password value (owned by the password object).</doc> + <type name="guint8" c:type="const guchar*"/> + </return-value> + <parameters> + <instance-parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </instance-parameter> + <parameter name="length" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">location to place the length of the password.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </method> + <method name="get_warning" c:identifier="g_tls_password_get_warning" version="2.30"> + <doc xml:space="preserve">Get a user readable translated warning. Usually this warning is a +representation of the password flags returned from +g_tls_password_get_flags().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The warning.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_description" c:identifier="g_tls_password_set_description" version="2.30"> + <doc xml:space="preserve">Set a description string about what the password will be used for.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </instance-parameter> + <parameter name="description" transfer-ownership="none"> + <doc xml:space="preserve">The description of the password</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_flags" c:identifier="g_tls_password_set_flags" version="2.30"> + <doc xml:space="preserve">Set flags about the password.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">The flags about the password</doc> + <type name="TlsPasswordFlags" c:type="GTlsPasswordFlags"/> + </parameter> + </parameters> + </method> + <method name="set_value" c:identifier="g_tls_password_set_value" version="2.30"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the new password value</doc> + <array length="1" zero-terminated="0" c:type="const guchar*"> + <type name="guint8" c:type="guchar"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of the password, or -1</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + </parameters> + </method> + <method name="set_value_full" c:identifier="g_tls_password_set_value_full" version="2.30"> + <doc xml:space="preserve">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.)</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value for the password</doc> + <array length="1" zero-terminated="0" c:type="guchar*"> + <type name="guint8" c:type="guchar"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of the password, or -1</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a function to use to free the password.</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="set_warning" c:identifier="g_tls_password_set_warning" version="2.30"> + <doc xml:space="preserve">Set a user readable translated warning. Usually this warning is a +representation of the password flags returned from +g_tls_password_get_flags().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </instance-parameter> + <parameter name="warning" transfer-ownership="none"> + <doc xml:space="preserve">The user readable warning</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <property name="description" writable="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="flags" writable="1" transfer-ownership="none"> + <type name="TlsPasswordFlags"/> + </property> + <property name="warning" writable="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv"> + <type name="TlsPasswordPrivate" c:type="GTlsPasswordPrivate*"/> + </field> + </class> + <record name="TlsPasswordClass" c:type="GTlsPasswordClass" glib:is-gtype-struct-for="TlsPassword"> + <doc xml:space="preserve">Class structure for #GTlsPassword.</doc> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="get_value"> + <callback name="get_value"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The password value (owned by the password object).</doc> + <type name="guint8" c:type="const guchar*"/> + </return-value> + <parameters> + <parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </parameter> + <parameter name="length" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">location to place the length of the password.</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="set_value"> + <callback name="set_value"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="password" transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsPassword object</doc> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">the value for the password</doc> + <array length="2" zero-terminated="0" c:type="guchar*"> + <type name="guint8" c:type="guchar"/> + </array> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve">the length of the password, or -1</doc> + <type name="gssize" c:type="gssize"/> + </parameter> + <parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a function to use to free the password.</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_default_warning"> + <callback name="get_default_warning"> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="password" transfer-ownership="none"> + <type name="TlsPassword" c:type="GTlsPassword*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="4"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <bitfield name="TlsPasswordFlags" version="2.30" glib:type-name="GTlsPasswordFlags" glib:get-type="g_tls_password_flags_get_type" c:type="GTlsPasswordFlags"> + <doc xml:space="preserve">Various flags for the password.</doc> + <member name="none" value="0" c:identifier="G_TLS_PASSWORD_NONE" glib:nick="none"> + <doc xml:space="preserve">No flags</doc> + </member> + <member name="retry" value="2" c:identifier="G_TLS_PASSWORD_RETRY" glib:nick="retry"> + <doc xml:space="preserve">The password was wrong, and the user should retry.</doc> + </member> + <member name="many_tries" value="4" c:identifier="G_TLS_PASSWORD_MANY_TRIES" glib:nick="many-tries"> + <doc xml:space="preserve">Hint to the user that the password has been + wrong many times, and the user may not have many chances left.</doc> + </member> + <member name="final_try" value="8" c:identifier="G_TLS_PASSWORD_FINAL_TRY" glib:nick="final-try"> + <doc xml:space="preserve">Hint to the user that this is the last try to get + this password right.</doc> + </member> + </bitfield> + <record name="TlsPasswordPrivate" c:type="GTlsPasswordPrivate" disguised="1"/> + <enumeration name="TlsRehandshakeMode" version="2.28" deprecated="1" deprecated-version="2.60." glib:type-name="GTlsRehandshakeMode" glib:get-type="g_tls_rehandshake_mode_get_type" c:type="GTlsRehandshakeMode"> + <doc xml:space="preserve">When to allow rehandshaking. See +g_tls_connection_set_rehandshake_mode().</doc> + <doc-deprecated xml:space="preserve">Changing the rehandshake mode is no longer + required for compatibility. Also, rehandshaking has been removed + from the TLS protocol in TLS 1.3.</doc-deprecated> + <member name="never" value="0" c:identifier="G_TLS_REHANDSHAKE_NEVER" glib:nick="never"> + <doc xml:space="preserve">Never allow rehandshaking</doc> + </member> + <member name="safely" value="1" c:identifier="G_TLS_REHANDSHAKE_SAFELY" glib:nick="safely"> + <doc xml:space="preserve">Allow safe rehandshaking only</doc> + </member> + <member name="unsafely" value="2" c:identifier="G_TLS_REHANDSHAKE_UNSAFELY" glib:nick="unsafely"> + <doc xml:space="preserve">Allow unsafe rehandshaking</doc> + </member> + </enumeration> + <interface name="TlsServerConnection" c:symbol-prefix="tls_server_connection" c:type="GTlsServerConnection" version="2.28" glib:type-name="GTlsServerConnection" glib:get-type="g_tls_server_connection_get_type" glib:type-struct="TlsServerConnectionInterface"> + <doc xml:space="preserve">#GTlsServerConnection is the server-side subclass of #GTlsConnection, +representing a server-side TLS connection.</doc> + <prerequisite name="TlsConnection"/> + <function name="new" c:identifier="g_tls_server_connection_new" version="2.28" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new +#GTlsServerConnection, or %NULL on error</doc> + <type name="TlsServerConnection" c:type="GIOStream*"/> + </return-value> + <parameters> + <parameter name="base_io_stream" transfer-ownership="none"> + <doc xml:space="preserve">the #GIOStream to wrap</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="certificate" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the default server certificate, or %NULL</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + </parameters> + </function> + <property name="authentication-mode" version="2.28" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="TlsAuthenticationMode"/> + </property> + </interface> + <record name="TlsServerConnectionInterface" c:type="GTlsServerConnectionInterface" glib:is-gtype-struct-for="TlsServerConnection" version="2.26"> + <doc xml:space="preserve">vtable for a #GTlsServerConnection implementation.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + </record> + <function-macro name="UNIX_CONNECTION" c:identifier="G_UNIX_CONNECTION" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_CONNECTION_CLASS" c:identifier="G_UNIX_CONNECTION_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_CONNECTION_GET_CLASS" c:identifier="G_UNIX_CONNECTION_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_CREDENTIALS_MESSAGE" c:identifier="G_UNIX_CREDENTIALS_MESSAGE" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_CREDENTIALS_MESSAGE_CLASS" c:identifier="G_UNIX_CREDENTIALS_MESSAGE_CLASS" introspectable="0"> + <parameters> + <parameter name="c"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_CREDENTIALS_MESSAGE_GET_CLASS" c:identifier="G_UNIX_CREDENTIALS_MESSAGE_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_FD_LIST" c:identifier="G_UNIX_FD_LIST" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_FD_LIST_CLASS" c:identifier="G_UNIX_FD_LIST_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_FD_LIST_GET_CLASS" c:identifier="G_UNIX_FD_LIST_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_FD_MESSAGE" c:identifier="G_UNIX_FD_MESSAGE" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_FD_MESSAGE_CLASS" c:identifier="G_UNIX_FD_MESSAGE_CLASS" introspectable="0"> + <parameters> + <parameter name="class"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_FD_MESSAGE_GET_CLASS" c:identifier="G_UNIX_FD_MESSAGE_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_INPUT_STREAM" c:identifier="G_UNIX_INPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_INPUT_STREAM_CLASS" c:identifier="G_UNIX_INPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_INPUT_STREAM_GET_CLASS" c:identifier="G_UNIX_INPUT_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_MOUNT_MONITOR" c:identifier="G_UNIX_MOUNT_MONITOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_MOUNT_MONITOR_CLASS" c:identifier="G_UNIX_MOUNT_MONITOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_OUTPUT_STREAM" c:identifier="G_UNIX_OUTPUT_STREAM" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_OUTPUT_STREAM_CLASS" c:identifier="G_UNIX_OUTPUT_STREAM_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_OUTPUT_STREAM_GET_CLASS" c:identifier="G_UNIX_OUTPUT_STREAM_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_SOCKET_ADDRESS" c:identifier="G_UNIX_SOCKET_ADDRESS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_SOCKET_ADDRESS_CLASS" c:identifier="G_UNIX_SOCKET_ADDRESS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="UNIX_SOCKET_ADDRESS_GET_CLASS" c:identifier="G_UNIX_SOCKET_ADDRESS_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <class name="UnixConnection" c:symbol-prefix="unix_connection" c:type="GUnixConnection" version="2.22" parent="SocketConnection" glib:type-name="GUnixConnection" glib:get-type="g_unix_connection_get_type" glib:type-struct="UnixConnectionClass"> + <doc xml:space="preserve">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.</doc> + <method name="receive_credentials" c:identifier="g_unix_connection_receive_credentials" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">Received credentials on success (free with +g_object_unref()), %NULL if @error is set.</doc> + <type name="Credentials" c:type="GCredentials*"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GUnixConnection.</doc> + <type name="UnixConnection" c:type="GUnixConnection*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="receive_credentials_async" c:identifier="g_unix_connection_receive_credentials_async" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GUnixConnection.</doc> + <type name="UnixConnection" c:type="GUnixConnection*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="receive_credentials_finish" c:identifier="g_unix_connection_receive_credentials_finish" version="2.32" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous receive credentials operation started with +g_unix_connection_receive_credentials_async().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GCredentials, or %NULL on error. + Free the returned object with g_object_unref().</doc> + <type name="Credentials" c:type="GCredentials*"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GUnixConnection.</doc> + <type name="UnixConnection" c:type="GUnixConnection*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="receive_fd" c:identifier="g_unix_connection_receive_fd" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a file descriptor on success, -1 on error.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixConnection</doc> + <type name="UnixConnection" c:type="GUnixConnection*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="send_credentials" c:identifier="g_unix_connection_send_credentials" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if @error is set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GUnixConnection.</doc> + <type name="UnixConnection" c:type="GUnixConnection*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="send_credentials_async" c:identifier="g_unix_connection_send_credentials_async" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GUnixConnection.</doc> + <type name="UnixConnection" c:type="GUnixConnection*"/> + </instance-parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="send_credentials_finish" c:identifier="g_unix_connection_send_credentials_finish" version="2.32" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous send credentials operation started with +g_unix_connection_send_credentials_async().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the operation was successful, otherwise %FALSE.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GUnixConnection.</doc> + <type name="UnixConnection" c:type="GUnixConnection*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult.</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="send_fd" c:identifier="g_unix_connection_send_fd" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a %TRUE on success, %NULL on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixConnection</doc> + <type name="UnixConnection" c:type="GUnixConnection*"/> + </instance-parameter> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a file descriptor</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="SocketConnection" c:type="GSocketConnection"/> + </field> + <field name="priv"> + <type name="UnixConnectionPrivate" c:type="GUnixConnectionPrivate*"/> + </field> + </class> + <record name="UnixConnectionClass" c:type="GUnixConnectionClass" glib:is-gtype-struct-for="UnixConnection"> + <field name="parent_class"> + <type name="SocketConnectionClass" c:type="GSocketConnectionClass"/> + </field> + </record> + <record name="UnixConnectionPrivate" c:type="GUnixConnectionPrivate" disguised="1"/> + <class name="UnixCredentialsMessage" c:symbol-prefix="unix_credentials_message" c:type="GUnixCredentialsMessage" version="2.26" parent="SocketControlMessage" glib:type-name="GUnixCredentialsMessage" glib:get-type="g_unix_credentials_message_get_type" glib:type-struct="UnixCredentialsMessageClass"> + <doc xml:space="preserve">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().</doc> + <constructor name="new" c:identifier="g_unix_credentials_message_new" version="2.26"> + <doc xml:space="preserve">Creates a new #GUnixCredentialsMessage with credentials matching the current processes.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUnixCredentialsMessage</doc> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </return-value> + </constructor> + <constructor name="new_with_credentials" c:identifier="g_unix_credentials_message_new_with_credentials" version="2.26"> + <doc xml:space="preserve">Creates a new #GUnixCredentialsMessage holding @credentials.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUnixCredentialsMessage</doc> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </return-value> + <parameters> + <parameter name="credentials" transfer-ownership="none"> + <doc xml:space="preserve">A #GCredentials object.</doc> + <type name="Credentials" c:type="GCredentials*"/> + </parameter> + </parameters> + </constructor> + <function name="is_supported" c:identifier="g_unix_credentials_message_is_supported" version="2.26"> + <doc xml:space="preserve">Checks if passing #GCredentials on a #GSocket is supported on this platform.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if supported, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + </function> + <method name="get_credentials" c:identifier="g_unix_credentials_message_get_credentials" version="2.26"> + <doc xml:space="preserve">Gets the credentials stored in @message.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">A #GCredentials instance. Do not free, it is owned by @message.</doc> + <type name="Credentials" c:type="GCredentials*"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">A #GUnixCredentialsMessage.</doc> + <type name="UnixCredentialsMessage" c:type="GUnixCredentialsMessage*"/> + </instance-parameter> + </parameters> + </method> + <property name="credentials" version="2.26" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The credentials stored in the message.</doc> + <type name="Credentials"/> + </property> + <field name="parent_instance"> + <type name="SocketControlMessage" c:type="GSocketControlMessage"/> + </field> + <field name="priv"> + <type name="UnixCredentialsMessagePrivate" c:type="GUnixCredentialsMessagePrivate*"/> + </field> + </class> + <record name="UnixCredentialsMessageClass" c:type="GUnixCredentialsMessageClass" glib:is-gtype-struct-for="UnixCredentialsMessage" version="2.26"> + <doc xml:space="preserve">Class structure for #GUnixCredentialsMessage.</doc> + <field name="parent_class"> + <type name="SocketControlMessageClass" c:type="GSocketControlMessageClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="UnixCredentialsMessagePrivate" c:type="GUnixCredentialsMessagePrivate" disguised="1"/> + <class name="UnixFDList" c:symbol-prefix="unix_fd_list" c:type="GUnixFDList" parent="GObject.Object" glib:type-name="GUnixFDList" glib:get-type="g_unix_fd_list_get_type" glib:type-struct="UnixFDListClass"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_unix_fd_list_new" version="2.24"> + <doc xml:space="preserve">Creates a new #GUnixFDList containing no file descriptors.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUnixFDList</doc> + <type name="UnixFDList" c:type="GUnixFDList*"/> + </return-value> + </constructor> + <constructor name="new_from_array" c:identifier="g_unix_fd_list_new_from_array" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUnixFDList</doc> + <type name="UnixFDList" c:type="GUnixFDList*"/> + </return-value> + <parameters> + <parameter name="fds" transfer-ownership="none"> + <doc xml:space="preserve">the initial list of file descriptors</doc> + <array length="1" zero-terminated="0" c:type="const gint*"> + <type name="gint" c:type="gint"/> + </array> + </parameter> + <parameter name="n_fds" transfer-ownership="none"> + <doc xml:space="preserve">the length of #fds, or -1</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </constructor> + <method name="append" c:identifier="g_unix_fd_list_append" version="2.24" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the index of the appended fd in case of success, else -1 + (and @error is set)</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixFDList</doc> + <type name="UnixFDList" c:type="GUnixFDList*"/> + </instance-parameter> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a valid open file descriptor</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="get" c:identifier="g_unix_fd_list_get" version="2.24" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the file descriptor, or -1 in case of error</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixFDList</doc> + <type name="UnixFDList" c:type="GUnixFDList*"/> + </instance-parameter> + <parameter name="index_" transfer-ownership="none"> + <doc xml:space="preserve">the index into the list</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="get_length" c:identifier="g_unix_fd_list_get_length" version="2.24"> + <doc xml:space="preserve">Gets the length of @list (ie: the number of file descriptors +contained within).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the length of @list</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixFDList</doc> + <type name="UnixFDList" c:type="GUnixFDList*"/> + </instance-parameter> + </parameters> + </method> + <method name="peek_fds" c:identifier="g_unix_fd_list_peek_fds" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an array of file + descriptors</doc> + <array length="0" zero-terminated="0" c:type="const gint*"> + <type name="gint" c:type="gint"/> + </array> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixFDList</doc> + <type name="UnixFDList" c:type="GUnixFDList*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">pointer to the length of the returned + array, or %NULL</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </method> + <method name="steal_fds" c:identifier="g_unix_fd_list_steal_fds" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an array of file + descriptors</doc> + <array length="0" zero-terminated="0" c:type="gint*"> + <type name="gint" c:type="gint"/> + </array> + </return-value> + <parameters> + <instance-parameter name="list" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixFDList</doc> + <type name="UnixFDList" c:type="GUnixFDList*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">pointer to the length of the returned + array, or %NULL</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv"> + <type name="UnixFDListPrivate" c:type="GUnixFDListPrivate*"/> + </field> + </class> + <record name="UnixFDListClass" c:type="GUnixFDListClass" glib:is-gtype-struct-for="UnixFDList"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="UnixFDListPrivate" c:type="GUnixFDListPrivate" disguised="1"/> + <class name="UnixFDMessage" c:symbol-prefix="unix_fd_message" c:type="GUnixFDMessage" parent="SocketControlMessage" glib:type-name="GUnixFDMessage" glib:get-type="g_unix_fd_message_get_type" glib:type-struct="UnixFDMessageClass"> + <doc xml:space="preserve">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.</doc> + <constructor name="new" c:identifier="g_unix_fd_message_new" version="2.22"> + <doc xml:space="preserve">Creates a new #GUnixFDMessage containing an empty file descriptor +list.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUnixFDMessage</doc> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </return-value> + </constructor> + <constructor name="new_with_fd_list" c:identifier="g_unix_fd_message_new_with_fd_list" version="2.24"> + <doc xml:space="preserve">Creates a new #GUnixFDMessage containing @list.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUnixFDMessage</doc> + <type name="SocketControlMessage" c:type="GSocketControlMessage*"/> + </return-value> + <parameters> + <parameter name="fd_list" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixFDList</doc> + <type name="UnixFDList" c:type="GUnixFDList*"/> + </parameter> + </parameters> + </constructor> + <method name="append_fd" c:identifier="g_unix_fd_message_append_fd" version="2.22" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE in case of success, else %FALSE (and @error is set)</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixFDMessage</doc> + <type name="UnixFDMessage" c:type="GUnixFDMessage*"/> + </instance-parameter> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a valid open file descriptor</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </method> + <method name="get_fd_list" c:identifier="g_unix_fd_message_get_fd_list" version="2.24"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GUnixFDList from @message</doc> + <type name="UnixFDList" c:type="GUnixFDList*"/> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixFDMessage</doc> + <type name="UnixFDMessage" c:type="GUnixFDMessage*"/> + </instance-parameter> + </parameters> + </method> + <method name="steal_fds" c:identifier="g_unix_fd_message_steal_fds" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an array of file + descriptors</doc> + <array length="0" zero-terminated="0" c:type="gint*"> + <type name="gint" c:type="gint"/> + </array> + </return-value> + <parameters> + <instance-parameter name="message" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixFDMessage</doc> + <type name="UnixFDMessage" c:type="GUnixFDMessage*"/> + </instance-parameter> + <parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">pointer to the length of the returned + array, or %NULL</doc> + <type name="gint" c:type="gint*"/> + </parameter> + </parameters> + </method> + <property name="fd-list" writable="1" construct-only="1" transfer-ownership="none"> + <type name="UnixFDList"/> + </property> + <field name="parent_instance"> + <type name="SocketControlMessage" c:type="GSocketControlMessage"/> + </field> + <field name="priv"> + <type name="UnixFDMessagePrivate" c:type="GUnixFDMessagePrivate*"/> + </field> + </class> + <record name="UnixFDMessageClass" c:type="GUnixFDMessageClass" glib:is-gtype-struct-for="UnixFDMessage"> + <field name="parent_class"> + <type name="SocketControlMessageClass" c:type="GSocketControlMessageClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="UnixFDMessagePrivate" c:type="GUnixFDMessagePrivate" disguised="1"/> + <class name="UnixInputStream" c:symbol-prefix="unix_input_stream" c:type="GUnixInputStream" parent="InputStream" glib:type-name="GUnixInputStream" glib:get-type="g_unix_input_stream_get_type" glib:type-struct="UnixInputStreamClass"> + <doc xml:space="preserve">#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.</doc> + <implements name="FileDescriptorBased"/> + <implements name="PollableInputStream"/> + <constructor name="new" c:identifier="g_unix_input_stream_new"> + <doc xml:space="preserve">Creates a new #GUnixInputStream for the given @fd. + +If @close_fd is %TRUE, the file descriptor will be closed +when the stream is closed.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUnixInputStream</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a UNIX file descriptor</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="close_fd" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to close the file descriptor when done</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </constructor> + <method name="get_close_fd" c:identifier="g_unix_input_stream_get_close_fd" version="2.20"> + <doc xml:space="preserve">Returns whether the file descriptor of @stream will be +closed when the stream is closed.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the file descriptor is closed when done</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixInputStream</doc> + <type name="UnixInputStream" c:type="GUnixInputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_fd" c:identifier="g_unix_input_stream_get_fd" version="2.20"> + <doc xml:space="preserve">Return the UNIX file descriptor that the stream reads from.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The file descriptor of @stream</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixInputStream</doc> + <type name="UnixInputStream" c:type="GUnixInputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_close_fd" c:identifier="g_unix_input_stream_set_close_fd" version="2.20"> + <doc xml:space="preserve">Sets whether the file descriptor of @stream shall be closed +when the stream is closed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixInputStream</doc> + <type name="UnixInputStream" c:type="GUnixInputStream*"/> + </instance-parameter> + <parameter name="close_fd" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to close the file descriptor when done</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <property name="close-fd" version="2.20" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">Whether to close the file descriptor when the stream is closed.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="fd" version="2.20" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The file descriptor that the stream reads from.</doc> + <type name="gint" c:type="gint"/> + </property> + <field name="parent_instance"> + <type name="InputStream" c:type="GInputStream"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="UnixInputStreamPrivate" c:type="GUnixInputStreamPrivate*"/> + </field> + </class> + <record name="UnixInputStreamClass" c:type="GUnixInputStreamClass" glib:is-gtype-struct-for="UnixInputStream"> + <field name="parent_class"> + <type name="InputStreamClass" c:type="GInputStreamClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="UnixInputStreamPrivate" c:type="GUnixInputStreamPrivate" disguised="1"/> + <record name="UnixMountEntry" c:type="GUnixMountEntry" glib:type-name="GUnixMountEntry" glib:get-type="g_unix_mount_entry_get_type" c:symbol-prefix="unix_mount_entry"> + <doc xml:space="preserve">Defines a Unix mount entry (e.g. <filename>/media/cdrom</filename>). +This corresponds roughly to a mtab entry.</doc> + </record> + <class name="UnixMountMonitor" c:symbol-prefix="unix_mount_monitor" c:type="GUnixMountMonitor" parent="GObject.Object" glib:type-name="GUnixMountMonitor" glib:get-type="g_unix_mount_monitor_get_type" glib:type-struct="UnixMountMonitorClass"> + <doc xml:space="preserve">Watches #GUnixMounts for changes.</doc> + <constructor name="new" c:identifier="g_unix_mount_monitor_new" deprecated="1" deprecated-version="2.44"> + <doc xml:space="preserve">Deprecated alias for g_unix_mount_monitor_get(). + +This function was never a true constructor, which is why it was +renamed.</doc> + <doc-deprecated xml:space="preserve">Use g_unix_mount_monitor_get() instead.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GUnixMountMonitor.</doc> + <type name="UnixMountMonitor" c:type="GUnixMountMonitor*"/> + </return-value> + </constructor> + <function name="get" c:identifier="g_unix_mount_monitor_get" version="2.44"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the #GUnixMountMonitor.</doc> + <type name="UnixMountMonitor" c:type="GUnixMountMonitor*"/> + </return-value> + </function> + <method name="set_rate_limit" c:identifier="g_unix_mount_monitor_set_rate_limit" version="2.18" deprecated="1" deprecated-version="2.44"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">This function does nothing. Don't call it.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount_monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountMonitor</doc> + <type name="UnixMountMonitor" c:type="GUnixMountMonitor*"/> + </instance-parameter> + <parameter name="limit_msec" transfer-ownership="none"> + <doc xml:space="preserve">a integer with the limit in milliseconds to + poll for changes.</doc> + <type name="gint" c:type="int"/> + </parameter> + </parameters> + </method> + <glib:signal name="mountpoints-changed" when="last"> + <doc xml:space="preserve">Emitted when the unix mount points have changed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + <glib:signal name="mounts-changed" when="last"> + <doc xml:space="preserve">Emitted when the unix mounts have changed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + </class> + <record name="UnixMountMonitorClass" c:type="GUnixMountMonitorClass" disguised="1" glib:is-gtype-struct-for="UnixMountMonitor"/> + <record name="UnixMountPoint" c:type="GUnixMountPoint" glib:type-name="GUnixMountPoint" glib:get-type="g_unix_mount_point_get_type" c:symbol-prefix="unix_mount_point"> + <doc xml:space="preserve">Defines a Unix mount point (e.g. <filename>/dev</filename>). +This corresponds roughly to a fstab entry.</doc> + <method name="compare" c:identifier="g_unix_mount_point_compare"> + <doc xml:space="preserve">Compares two unix mount points.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">1, 0 or -1 if @mount1 is greater than, equal to, +or less than @mount2, respectively.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="mount1" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMount.</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </instance-parameter> + <parameter name="mount2" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMount.</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </parameter> + </parameters> + </method> + <method name="copy" c:identifier="g_unix_mount_point_copy" version="2.54"> + <doc xml:space="preserve">Makes a copy of @mount_point.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUnixMountPoint</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </return-value> + <parameters> + <instance-parameter name="mount_point" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountPoint.</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </instance-parameter> + </parameters> + </method> + <method name="free" c:identifier="g_unix_mount_point_free"> + <doc xml:space="preserve">Frees a unix mount point.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="mount_point" transfer-ownership="none"> + <doc xml:space="preserve">unix mount point to free.</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_device_path" c:identifier="g_unix_mount_point_get_device_path"> + <doc xml:space="preserve">Gets the device path for a unix mount point.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a string containing the device path.</doc> + <type name="filename" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="mount_point" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountPoint.</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_fs_type" c:identifier="g_unix_mount_point_get_fs_type"> + <doc xml:space="preserve">Gets the file system type for the mount point.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a string containing the file system type.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="mount_point" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountPoint.</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_mount_path" c:identifier="g_unix_mount_point_get_mount_path"> + <doc xml:space="preserve">Gets the mount path for a unix mount point.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a string containing the mount path.</doc> + <type name="filename" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="mount_point" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountPoint.</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_options" c:identifier="g_unix_mount_point_get_options" version="2.32"> + <doc xml:space="preserve">Gets the options for the mount point.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing the options.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="mount_point" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountPoint.</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </instance-parameter> + </parameters> + </method> + <method name="guess_can_eject" c:identifier="g_unix_mount_point_guess_can_eject"> + <doc xml:space="preserve">Guesses whether a Unix mount point can be ejected.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @mount_point is deemed to be ejectable.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount_point" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountPoint</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </instance-parameter> + </parameters> + </method> + <method name="guess_icon" c:identifier="g_unix_mount_point_guess_icon"> + <doc xml:space="preserve">Guesses the icon of a Unix mount point.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="mount_point" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountPoint</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </instance-parameter> + </parameters> + </method> + <method name="guess_name" c:identifier="g_unix_mount_point_guess_name"> + <doc xml:space="preserve">Guesses the name of a Unix mount point. +The result is a translated string.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A newly allocated string that must + be freed with g_free()</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="mount_point" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountPoint</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </instance-parameter> + </parameters> + </method> + <method name="guess_symbolic_icon" c:identifier="g_unix_mount_point_guess_symbolic_icon" version="2.34"> + <doc xml:space="preserve">Guesses the symbolic icon of a Unix mount point.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="mount_point" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountPoint</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_loopback" c:identifier="g_unix_mount_point_is_loopback"> + <doc xml:space="preserve">Checks if a unix mount point is a loopback device.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount point is a loopback. %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount_point" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountPoint.</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_readonly" c:identifier="g_unix_mount_point_is_readonly"> + <doc xml:space="preserve">Checks if a unix mount point is read only.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if a mount point is read only.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount_point" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountPoint.</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_user_mountable" c:identifier="g_unix_mount_point_is_user_mountable"> + <doc xml:space="preserve">Checks if a unix mount point is mountable by the user.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount point is user mountable.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="mount_point" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountPoint.</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </instance-parameter> + </parameters> + </method> + <function name="at" c:identifier="g_unix_mount_point_at" version="2.66"> + <doc xml:space="preserve">Gets a #GUnixMountPoint for a given mount path. If @time_read is set, it +will be filled with a unix timestamp for checking if the mount points have +changed since with g_unix_mount_points_changed_since(). + +If more mount points have the same mount path, the last matching mount point +is returned.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GUnixMountPoint, or %NULL if no match +is found.</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </return-value> + <parameters> + <parameter name="mount_path" transfer-ownership="none"> + <doc xml:space="preserve">path for a possible unix mount point.</doc> + <type name="filename" c:type="const char*"/> + </parameter> + <parameter name="time_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">guint64 to contain a timestamp.</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + </parameters> + </function> + </record> + <class name="UnixOutputStream" c:symbol-prefix="unix_output_stream" c:type="GUnixOutputStream" parent="OutputStream" glib:type-name="GUnixOutputStream" glib:get-type="g_unix_output_stream_get_type" glib:type-struct="UnixOutputStreamClass"> + <doc xml:space="preserve">#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.</doc> + <implements name="FileDescriptorBased"/> + <implements name="PollableOutputStream"/> + <constructor name="new" c:identifier="g_unix_output_stream_new"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GOutputStream</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </return-value> + <parameters> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve">a UNIX file descriptor</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="close_fd" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to close the file descriptor when done</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </constructor> + <method name="get_close_fd" c:identifier="g_unix_output_stream_get_close_fd" version="2.20"> + <doc xml:space="preserve">Returns whether the file descriptor of @stream will be +closed when the stream is closed.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the file descriptor is closed when done</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixOutputStream</doc> + <type name="UnixOutputStream" c:type="GUnixOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_fd" c:identifier="g_unix_output_stream_get_fd" version="2.20"> + <doc xml:space="preserve">Return the UNIX file descriptor that the stream writes to.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">The file descriptor of @stream</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixOutputStream</doc> + <type name="UnixOutputStream" c:type="GUnixOutputStream*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_close_fd" c:identifier="g_unix_output_stream_set_close_fd" version="2.20"> + <doc xml:space="preserve">Sets whether the file descriptor of @stream shall be closed +when the stream is closed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixOutputStream</doc> + <type name="UnixOutputStream" c:type="GUnixOutputStream*"/> + </instance-parameter> + <parameter name="close_fd" transfer-ownership="none"> + <doc xml:space="preserve">%TRUE to close the file descriptor when done</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <property name="close-fd" version="2.20" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">Whether to close the file descriptor when the stream is closed.</doc> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="fd" version="2.20" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">The file descriptor that the stream writes to.</doc> + <type name="gint" c:type="gint"/> + </property> + <field name="parent_instance"> + <type name="OutputStream" c:type="GOutputStream"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="UnixOutputStreamPrivate" c:type="GUnixOutputStreamPrivate*"/> + </field> + </class> + <record name="UnixOutputStreamClass" c:type="GUnixOutputStreamClass" glib:is-gtype-struct-for="UnixOutputStream"> + <field name="parent_class"> + <type name="OutputStreamClass" c:type="GOutputStreamClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="UnixOutputStreamPrivate" c:type="GUnixOutputStreamPrivate" disguised="1"/> + <class name="UnixSocketAddress" c:symbol-prefix="unix_socket_address" c:type="GUnixSocketAddress" parent="SocketAddress" glib:type-name="GUnixSocketAddress" glib:get-type="g_unix_socket_address_get_type" glib:type-struct="UnixSocketAddressClass"> + <doc xml:space="preserve">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.</doc> + <implements name="SocketConnectable"/> + <constructor name="new" c:identifier="g_unix_socket_address_new" version="2.22"> + <doc xml:space="preserve">Creates a new #GUnixSocketAddress for @path. + +To create abstract socket addresses, on systems that support that, +use g_unix_socket_address_new_abstract().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUnixSocketAddress</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the socket path</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_abstract" c:identifier="g_unix_socket_address_new_abstract" deprecated="1"> + <doc xml:space="preserve">Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED +#GUnixSocketAddress for @path.</doc> + <doc-deprecated xml:space="preserve">Use g_unix_socket_address_new_with_type().</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUnixSocketAddress</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the abstract name</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="gchar"/> + </array> + </parameter> + <parameter name="path_len" transfer-ownership="none"> + <doc xml:space="preserve">the length of @path, or -1</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_with_type" c:identifier="g_unix_socket_address_new_with_type" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUnixSocketAddress</doc> + <type name="SocketAddress" c:type="GSocketAddress*"/> + </return-value> + <parameters> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">the name</doc> + <array length="1" zero-terminated="0" c:type="const gchar*"> + <type name="gchar"/> + </array> + </parameter> + <parameter name="path_len" transfer-ownership="none"> + <doc xml:space="preserve">the length of @path, or -1</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixSocketAddressType</doc> + <type name="UnixSocketAddressType" c:type="GUnixSocketAddressType"/> + </parameter> + </parameters> + </constructor> + <function name="abstract_names_supported" c:identifier="g_unix_socket_address_abstract_names_supported" version="2.22"> + <doc xml:space="preserve">Checks if abstract UNIX domain socket names are supported.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if supported, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + </function> + <method name="get_address_type" c:identifier="g_unix_socket_address_get_address_type" version="2.26"> + <doc xml:space="preserve">Gets @address's type.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixSocketAddressType</doc> + <type name="UnixSocketAddressType" c:type="GUnixSocketAddressType"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetSocketAddress</doc> + <type name="UnixSocketAddress" c:type="GUnixSocketAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_is_abstract" c:identifier="g_unix_socket_address_get_is_abstract" version="2.22" deprecated="1"> + <doc xml:space="preserve">Tests if @address is abstract.</doc> + <doc-deprecated xml:space="preserve">Use g_unix_socket_address_get_address_type()</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the address is abstract, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetSocketAddress</doc> + <type name="UnixSocketAddress" c:type="GUnixSocketAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_path" c:identifier="g_unix_socket_address_get_path" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the path for @address</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetSocketAddress</doc> + <type name="UnixSocketAddress" c:type="GUnixSocketAddress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_path_len" c:identifier="g_unix_socket_address_get_path_len" version="2.22"> + <doc xml:space="preserve">Gets the length of @address's path. + +For details, see g_unix_socket_address_get_path().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the length of the path</doc> + <type name="gsize" c:type="gsize"/> + </return-value> + <parameters> + <instance-parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">a #GInetSocketAddress</doc> + <type name="UnixSocketAddress" c:type="GUnixSocketAddress*"/> + </instance-parameter> + </parameters> + </method> + <property name="abstract" deprecated="1" writable="1" construct-only="1" transfer-ownership="none"> + <doc xml:space="preserve">Whether or not this is an abstract address</doc> + <doc-deprecated xml:space="preserve">Use #GUnixSocketAddress:address-type, which +distinguishes between zero-padded and non-zero-padded +abstract addresses.</doc-deprecated> + <type name="gboolean" c:type="gboolean"/> + </property> + <property name="address-type" writable="1" construct-only="1" transfer-ownership="none"> + <type name="UnixSocketAddressType"/> + </property> + <property name="path" writable="1" construct-only="1" transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="path-as-array" writable="1" construct-only="1" transfer-ownership="none"> + <array name="GLib.ByteArray"> + <type name="guint8" c:type="guint8"/> + </array> + </property> + <field name="parent_instance"> + <type name="SocketAddress" c:type="GSocketAddress"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="UnixSocketAddressPrivate" c:type="GUnixSocketAddressPrivate*"/> + </field> + </class> + <record name="UnixSocketAddressClass" c:type="GUnixSocketAddressClass" glib:is-gtype-struct-for="UnixSocketAddress"> + <field name="parent_class"> + <type name="SocketAddressClass" c:type="GSocketAddressClass"/> + </field> + </record> + <record name="UnixSocketAddressPrivate" c:type="GUnixSocketAddressPrivate" disguised="1"/> + <enumeration name="UnixSocketAddressType" version="2.26" glib:type-name="GUnixSocketAddressType" glib:get-type="g_unix_socket_address_type_get_type" c:type="GUnixSocketAddressType"> + <doc xml:space="preserve">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.</doc> + <member name="invalid" value="0" c:identifier="G_UNIX_SOCKET_ADDRESS_INVALID" glib:nick="invalid"> + <doc xml:space="preserve">invalid</doc> + </member> + <member name="anonymous" value="1" c:identifier="G_UNIX_SOCKET_ADDRESS_ANONYMOUS" glib:nick="anonymous"> + <doc xml:space="preserve">anonymous</doc> + </member> + <member name="path" value="2" c:identifier="G_UNIX_SOCKET_ADDRESS_PATH" glib:nick="path"> + <doc xml:space="preserve">a filesystem path</doc> + </member> + <member name="abstract" value="3" c:identifier="G_UNIX_SOCKET_ADDRESS_ABSTRACT" glib:nick="abstract"> + <doc xml:space="preserve">an abstract name</doc> + </member> + <member name="abstract_padded" value="4" c:identifier="G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED" glib:nick="abstract-padded"> + <doc xml:space="preserve">an abstract name, 0-padded + to the full length of a unix socket name</doc> + </member> + </enumeration> + <function-macro name="VFS" c:identifier="G_VFS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="VFS_CLASS" c:identifier="G_VFS_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <constant name="VFS_EXTENSION_POINT_NAME" value="gio-vfs" c:type="G_VFS_EXTENSION_POINT_NAME"> + <doc xml:space="preserve">Extension point for #GVfs functionality. +See [Extending GIO][extending-gio].</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="VFS_GET_CLASS" c:identifier="G_VFS_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="VOLUME" c:identifier="G_VOLUME" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="VOLUME_GET_IFACE" c:identifier="G_VOLUME_GET_IFACE" introspectable="0"> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <constant name="VOLUME_IDENTIFIER_KIND_CLASS" value="class" c:type="G_VOLUME_IDENTIFIER_KIND_CLASS"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="VOLUME_IDENTIFIER_KIND_HAL_UDI" value="hal-udi" c:type="G_VOLUME_IDENTIFIER_KIND_HAL_UDI" deprecated="1" deprecated-version="2.58"> + <doc xml:space="preserve">The string used to obtain a Hal UDI with g_volume_get_identifier().</doc> + <doc-deprecated xml:space="preserve">Do not use, HAL is deprecated.</doc-deprecated> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="VOLUME_IDENTIFIER_KIND_LABEL" value="label" c:type="G_VOLUME_IDENTIFIER_KIND_LABEL"> + <doc xml:space="preserve">The string used to obtain a filesystem label with g_volume_get_identifier().</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="VOLUME_IDENTIFIER_KIND_NFS_MOUNT" value="nfs-mount" c:type="G_VOLUME_IDENTIFIER_KIND_NFS_MOUNT"> + <doc xml:space="preserve">The string used to obtain a NFS mount with g_volume_get_identifier().</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="VOLUME_IDENTIFIER_KIND_UNIX_DEVICE" value="unix-device" c:type="G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE"> + <doc xml:space="preserve">The string used to obtain a Unix device path with g_volume_get_identifier().</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="VOLUME_IDENTIFIER_KIND_UUID" value="uuid" c:type="G_VOLUME_IDENTIFIER_KIND_UUID"> + <doc xml:space="preserve">The string used to obtain a UUID with g_volume_get_identifier().</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="VOLUME_MONITOR" c:identifier="G_VOLUME_MONITOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="VOLUME_MONITOR_CLASS" c:identifier="G_VOLUME_MONITOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <constant name="VOLUME_MONITOR_EXTENSION_POINT_NAME" value="gio-volume-monitor" c:type="G_VOLUME_MONITOR_EXTENSION_POINT_NAME"> + <doc xml:space="preserve">Extension point for volume monitor functionality. +See [Extending GIO][extending-gio].</doc> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="VOLUME_MONITOR_GET_CLASS" c:identifier="G_VOLUME_MONITOR_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <class name="Vfs" c:symbol-prefix="vfs" c:type="GVfs" parent="GObject.Object" glib:type-name="GVfs" glib:get-type="g_vfs_get_type" glib:type-struct="VfsClass"> + <doc xml:space="preserve">Entry point for using GIO functionality.</doc> + <function name="get_default" c:identifier="g_vfs_get_default"> + <doc xml:space="preserve">Gets the default #GVfs for the system.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs, which will be the local + file system #GVfs if no other implementation is available.</doc> + <type name="Vfs" c:type="GVfs*"/> + </return-value> + </function> + <function name="get_local" c:identifier="g_vfs_get_local"> + <doc xml:space="preserve">Gets the local #GVfs for the system.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs.</doc> + <type name="Vfs" c:type="GVfs*"/> + </return-value> + </function> + <virtual-method name="add_writable_namespaces"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + <parameter name="list" transfer-ownership="none"> + <type name="FileAttributeInfoList" c:type="GFileAttributeInfoList*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="deserialize_icon" introspectable="0"> + <return-value> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + <parameter name="value" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_file_for_path" invoker="get_file_for_path"> + <doc xml:space="preserve">Gets a #GFile for @path.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs.</doc> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a VFS path.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_file_for_uri" invoker="get_file_for_uri"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a#GVfs.</doc> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a URI</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_supported_uri_schemes" invoker="get_supported_uri_schemes"> + <doc xml:space="preserve">Gets a list of URI schemes supported by @vfs.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a %NULL-terminated array of strings. + The returned array belongs to GIO and must + not be freed or modified.</doc> + <array c:type="const gchar* const*"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs.</doc> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="is_active" invoker="is_active"> + <doc xml:space="preserve">Checks if the VFS is active.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if construction of the @vfs was successful + and it is now active.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs.</doc> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="local_file_add_info"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + <parameter name="filename" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="device" transfer-ownership="none"> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="attribute_matcher" transfer-ownership="none"> + <type name="FileAttributeMatcher" c:type="GFileAttributeMatcher*"/> + </parameter> + <parameter name="info" transfer-ownership="none"> + <type name="FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="extra_data" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + <parameter name="free_extra_data" transfer-ownership="none" scope="async"> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="local_file_moved"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + <parameter name="source" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="dest" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="local_file_removed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + <parameter name="filename" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="local_file_set_attributes" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + <parameter name="filename" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="info" transfer-ownership="none"> + <type name="FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="parse_name" invoker="parse_name"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile for the given @parse_name. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs.</doc> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + <parameter name="parse_name" transfer-ownership="none"> + <doc xml:space="preserve">a string to be parsed by the VFS module.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_file_for_path" c:identifier="g_vfs_get_file_for_path"> + <doc xml:space="preserve">Gets a #GFile for @path.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs.</doc> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a VFS path.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_file_for_uri" c:identifier="g_vfs_get_file_for_uri"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a#GVfs.</doc> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a URI</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_supported_uri_schemes" c:identifier="g_vfs_get_supported_uri_schemes"> + <doc xml:space="preserve">Gets a list of URI schemes supported by @vfs.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a %NULL-terminated array of strings. + The returned array belongs to GIO and must + not be freed or modified.</doc> + <array c:type="const gchar* const*"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs.</doc> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_active" c:identifier="g_vfs_is_active"> + <doc xml:space="preserve">Checks if the VFS is active.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if construction of the @vfs was successful + and it is now active.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs.</doc> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + </parameters> + </method> + <method name="parse_name" c:identifier="g_vfs_parse_name"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile for the given @parse_name. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs.</doc> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + <parameter name="parse_name" transfer-ownership="none"> + <doc xml:space="preserve">a string to be parsed by the VFS module.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="register_uri_scheme" c:identifier="g_vfs_register_uri_scheme" version="2.50"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @scheme was successfully registered, or %FALSE if a handler + for @scheme already exists.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs</doc> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + <parameter name="scheme" transfer-ownership="none"> + <doc xml:space="preserve">an URI scheme, e.g. "http"</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="uri_func" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="2" destroy="3"> + <doc xml:space="preserve">a #GVfsFileLookupFunc</doc> + <type name="VfsFileLookupFunc" c:type="GVfsFileLookupFunc"/> + </parameter> + <parameter name="uri_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">custom data passed to be passed to @uri_func, or %NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="uri_destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">function to be called when unregistering the + URI scheme, or when @vfs is disposed, to free the resources used + by the URI lookup function</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + <parameter name="parse_name_func" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="5" destroy="6"> + <doc xml:space="preserve">a #GVfsFileLookupFunc</doc> + <type name="VfsFileLookupFunc" c:type="GVfsFileLookupFunc"/> + </parameter> + <parameter name="parse_name_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">custom data passed to be passed to + @parse_name_func, or %NULL</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="parse_name_destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">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</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </method> + <method name="unregister_uri_scheme" c:identifier="g_vfs_unregister_uri_scheme" version="2.50"> + <doc xml:space="preserve">Unregisters the URI handler for @scheme previously registered with +g_vfs_register_uri_scheme().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @scheme was successfully unregistered, or %FALSE if a + handler for @scheme does not exist.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs</doc> + <type name="Vfs" c:type="GVfs*"/> + </instance-parameter> + <parameter name="scheme" transfer-ownership="none"> + <doc xml:space="preserve">an URI scheme, e.g. "http"</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + </class> + <record name="VfsClass" c:type="GVfsClass" glib:is-gtype-struct-for="Vfs"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="is_active"> + <callback name="is_active"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if construction of the @vfs was successful + and it is now active.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs.</doc> + <type name="Vfs" c:type="GVfs*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_file_for_path"> + <callback name="get_file_for_path"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs.</doc> + <type name="Vfs" c:type="GVfs*"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a VFS path.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_file_for_uri"> + <callback name="get_file_for_uri"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a#GVfs.</doc> + <type name="Vfs" c:type="GVfs*"/> + </parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a URI</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_supported_uri_schemes"> + <callback name="get_supported_uri_schemes"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a %NULL-terminated array of strings. + The returned array belongs to GIO and must + not be freed or modified.</doc> + <array c:type="const gchar* const*"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs.</doc> + <type name="Vfs" c:type="GVfs*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="parse_name"> + <callback name="parse_name"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile for the given @parse_name. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs.</doc> + <type name="Vfs" c:type="GVfs*"/> + </parameter> + <parameter name="parse_name" transfer-ownership="none"> + <doc xml:space="preserve">a string to be parsed by the VFS module.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="local_file_add_info"> + <callback name="local_file_add_info"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="vfs" transfer-ownership="none"> + <type name="Vfs" c:type="GVfs*"/> + </parameter> + <parameter name="filename" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="device" transfer-ownership="none"> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="attribute_matcher" transfer-ownership="none"> + <type name="FileAttributeMatcher" c:type="GFileAttributeMatcher*"/> + </parameter> + <parameter name="info" transfer-ownership="none"> + <type name="FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="extra_data" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + <parameter name="free_extra_data" transfer-ownership="none" scope="async"> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="add_writable_namespaces"> + <callback name="add_writable_namespaces"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="vfs" transfer-ownership="none"> + <type name="Vfs" c:type="GVfs*"/> + </parameter> + <parameter name="list" transfer-ownership="none"> + <type name="FileAttributeInfoList" c:type="GFileAttributeInfoList*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="local_file_set_attributes"> + <callback name="local_file_set_attributes" throws="1"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="vfs" transfer-ownership="none"> + <type name="Vfs" c:type="GVfs*"/> + </parameter> + <parameter name="filename" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="info" transfer-ownership="none"> + <type name="FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <type name="FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="local_file_removed"> + <callback name="local_file_removed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="vfs" transfer-ownership="none"> + <type name="Vfs" c:type="GVfs*"/> + </parameter> + <parameter name="filename" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="local_file_moved"> + <callback name="local_file_moved"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="vfs" transfer-ownership="none"> + <type name="Vfs" c:type="GVfs*"/> + </parameter> + <parameter name="source" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="dest" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="deserialize_icon" introspectable="0"> + <callback name="deserialize_icon" introspectable="0"> + <return-value> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="vfs" transfer-ownership="none"> + <type name="Vfs" c:type="GVfs*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved6" introspectable="0"> + <callback name="_g_reserved6"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <callback name="VfsFileLookupFunc" c:type="GVfsFileLookupFunc" version="2.50"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GFile for @identifier.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="vfs" transfer-ownership="none"> + <doc xml:space="preserve">a #GVfs</doc> + <type name="Vfs" c:type="GVfs*"/> + </parameter> + <parameter name="identifier" transfer-ownership="none"> + <doc xml:space="preserve">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()</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2"> + <doc xml:space="preserve">user data passed to the function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <interface name="Volume" c:symbol-prefix="volume" c:type="GVolume" glib:type-name="GVolume" glib:get-type="g_volume_get_type" glib:type-struct="VolumeIface"> + <doc xml:space="preserve">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().</doc> + <virtual-method name="can_eject" invoker="can_eject"> + <doc xml:space="preserve">Checks if a volume can be ejected.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @volume can be ejected. %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="can_mount" invoker="can_mount"> + <doc xml:space="preserve">Checks if a volume can be mounted.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @volume can be mounted. %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="eject" invoker="eject" deprecated="1" deprecated-version="2.22"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_volume_eject_with_operation() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3"> + <doc xml:space="preserve">user data that gets passed to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="eject_finish" invoker="eject_finish" deprecated="1" deprecated-version="2.22" throws="1"> + <doc xml:space="preserve">Finishes ejecting a volume. If any errors occurred during the operation, +@error will be set to contain the errors and %FALSE will be returned.</doc> + <doc-deprecated xml:space="preserve">Use g_volume_eject_with_operation_finish() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE, %FALSE if operation failed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">pointer to a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="eject_with_operation" invoker="eject_with_operation" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to + avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data passed to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="eject_with_operation_finish" invoker="eject_with_operation_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes ejecting a volume. If any errors occurred during the operation, +@error will be set to contain the errors and %FALSE will be returned.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the volume was successfully ejected. %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="enumerate_identifiers" invoker="enumerate_identifiers"> + <doc xml:space="preserve">Gets the kinds of [identifiers][volume-identifier] that @volume has. +Use g_volume_get_identifier() to obtain the identifiers themselves.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated array + of strings containing kinds of identifiers. Use g_strfreev() to free.</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_activation_root" invoker="get_activation_root" version="2.18"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the activation root of @volume + or %NULL. Use g_object_unref() to free.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_drive" invoker="get_drive"> + <doc xml:space="preserve">Gets the drive for the @volume.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="Drive" c:type="GDrive*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_icon" invoker="get_icon"> + <doc xml:space="preserve">Gets the icon for @volume.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon. + The returned object should be unreffed with g_object_unref() + when no longer needed.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_identifier" invoker="get_identifier"> + <doc xml:space="preserve">Gets the identifier of the given kind for @volume. +See the [introduction][volume-identifier] for more +information about volume identifiers.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly allocated string containing the + requested identifier, or %NULL if the #GVolume + doesn't have this kind of identifier</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + <parameter name="kind" transfer-ownership="none"> + <doc xml:space="preserve">the kind of identifier to return</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_mount" invoker="get_mount"> + <doc xml:space="preserve">Gets the mount for the @volume.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GMount or %NULL if @volume isn't mounted. + The returned object should be unreffed with g_object_unref() + when no longer needed.</doc> + <type name="Mount" c:type="GMount*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_name" invoker="get_name"> + <doc xml:space="preserve">Gets the name of @volume.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the name for the given @volume. The returned string should + be freed with g_free() when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_sort_key" invoker="get_sort_key" version="2.32"> + <doc xml:space="preserve">Gets the sort key for @volume, if any.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">Sorting key for @volume or %NULL if no such key is available</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_symbolic_icon" invoker="get_symbolic_icon" version="2.34"> + <doc xml:space="preserve">Gets the symbolic icon for @volume.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon. + The returned object should be unreffed with g_object_unref() + when no longer needed.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_uuid" invoker="get_uuid"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="mount_finish" invoker="mount_finish" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE, %FALSE if operation failed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="mount_fn" invoker="mount"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountMountFlags" c:type="GMountMountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data that gets passed to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="removed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="should_automount" invoker="should_automount"> + <doc xml:space="preserve">Returns whether the volume should be automatically mounted.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the volume should be automatically mounted</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </virtual-method> + <method name="can_eject" c:identifier="g_volume_can_eject"> + <doc xml:space="preserve">Checks if a volume can be ejected.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @volume can be ejected. %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </method> + <method name="can_mount" c:identifier="g_volume_can_mount"> + <doc xml:space="preserve">Checks if a volume can be mounted.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @volume can be mounted. %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </method> + <method name="eject" c:identifier="g_volume_eject" deprecated="1" deprecated-version="2.22"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_volume_eject_with_operation() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data that gets passed to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="eject_finish" c:identifier="g_volume_eject_finish" deprecated="1" deprecated-version="2.22" throws="1"> + <doc xml:space="preserve">Finishes ejecting a volume. If any errors occurred during the operation, +@error will be set to contain the errors and %FALSE will be returned.</doc> + <doc-deprecated xml:space="preserve">Use g_volume_eject_with_operation_finish() instead.</doc-deprecated> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE, %FALSE if operation failed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">pointer to a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="eject_with_operation" c:identifier="g_volume_eject_with_operation" version="2.22"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to + avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="eject_with_operation_finish" c:identifier="g_volume_eject_with_operation_finish" version="2.22" throws="1"> + <doc xml:space="preserve">Finishes ejecting a volume. If any errors occurred during the operation, +@error will be set to contain the errors and %FALSE will be returned.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the volume was successfully ejected. %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="enumerate_identifiers" c:identifier="g_volume_enumerate_identifiers"> + <doc xml:space="preserve">Gets the kinds of [identifiers][volume-identifier] that @volume has. +Use g_volume_get_identifier() to obtain the identifiers themselves.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated array + of strings containing kinds of identifiers. Use g_strfreev() to free.</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_activation_root" c:identifier="g_volume_get_activation_root" version="2.18"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the activation root of @volume + or %NULL. Use g_object_unref() to free.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_drive" c:identifier="g_volume_get_drive"> + <doc xml:space="preserve">Gets the drive for the @volume.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="Drive" c:type="GDrive*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_icon" c:identifier="g_volume_get_icon"> + <doc xml:space="preserve">Gets the icon for @volume.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon. + The returned object should be unreffed with g_object_unref() + when no longer needed.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_identifier" c:identifier="g_volume_get_identifier"> + <doc xml:space="preserve">Gets the identifier of the given kind for @volume. +See the [introduction][volume-identifier] for more +information about volume identifiers.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly allocated string containing the + requested identifier, or %NULL if the #GVolume + doesn't have this kind of identifier</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + <parameter name="kind" transfer-ownership="none"> + <doc xml:space="preserve">the kind of identifier to return</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_mount" c:identifier="g_volume_get_mount"> + <doc xml:space="preserve">Gets the mount for the @volume.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GMount or %NULL if @volume isn't mounted. + The returned object should be unreffed with g_object_unref() + when no longer needed.</doc> + <type name="Mount" c:type="GMount*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_name" c:identifier="g_volume_get_name"> + <doc xml:space="preserve">Gets the name of @volume.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the name for the given @volume. The returned string should + be freed with g_free() when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_sort_key" c:identifier="g_volume_get_sort_key" version="2.32"> + <doc xml:space="preserve">Gets the sort key for @volume, if any.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">Sorting key for @volume or %NULL if no such key is available</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_symbolic_icon" c:identifier="g_volume_get_symbolic_icon" version="2.34"> + <doc xml:space="preserve">Gets the symbolic icon for @volume.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon. + The returned object should be unreffed with g_object_unref() + when no longer needed.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_uuid" c:identifier="g_volume_get_uuid"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </method> + <method name="mount" c:identifier="g_volume_mount"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountMountFlags" c:type="GMountMountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data that gets passed to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="mount_finish" c:identifier="g_volume_mount_finish" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE, %FALSE if operation failed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="should_automount" c:identifier="g_volume_should_automount"> + <doc xml:space="preserve">Returns whether the volume should be automatically mounted.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the volume should be automatically mounted</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </instance-parameter> + </parameters> + </method> + <glib:signal name="changed" when="last"> + <doc xml:space="preserve">Emitted when the volume has been changed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + <glib:signal name="removed" when="last"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + </interface> + <record name="VolumeIface" c:type="GVolumeIface" glib:is-gtype-struct-for="Volume"> + <doc xml:space="preserve">Interface for implementing operations for mountable volumes.</doc> + <field name="g_iface"> + <doc xml:space="preserve">The parent interface.</doc> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="changed"> + <callback name="changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="removed"> + <callback name="removed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_name"> + <callback name="get_name"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the name for the given @volume. The returned string should + be freed with g_free() when no longer needed.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_icon"> + <callback name="get_icon"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon. + The returned object should be unreffed with g_object_unref() + when no longer needed.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_uuid"> + <callback name="get_uuid"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_drive"> + <callback name="get_drive"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">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.</doc> + <type name="Drive" c:type="GDrive*"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_mount"> + <callback name="get_mount"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GMount or %NULL if @volume isn't mounted. + The returned object should be unreffed with g_object_unref() + when no longer needed.</doc> + <type name="Mount" c:type="GMount*"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_mount"> + <callback name="can_mount"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @volume can be mounted. %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="can_eject"> + <callback name="can_eject"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the @volume can be ejected. %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="mount_fn"> + <callback name="mount_fn"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the operation</doc> + <type name="MountMountFlags" c:type="GMountMountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">user data that gets passed to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="mount_finish"> + <callback name="mount_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE, %FALSE if operation failed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject"> + <callback name="eject"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4"> + <doc xml:space="preserve">user data that gets passed to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject_finish"> + <callback name="eject_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE, %FALSE if operation failed</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">pointer to a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_identifier"> + <callback name="get_identifier"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a newly allocated string containing the + requested identifier, or %NULL if the #GVolume + doesn't have this kind of identifier</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + <parameter name="kind" transfer-ownership="none"> + <doc xml:space="preserve">the kind of identifier to return</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="enumerate_identifiers"> + <callback name="enumerate_identifiers"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a %NULL-terminated array + of strings containing kinds of identifiers. Use g_strfreev() to free.</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="should_automount"> + <callback name="should_automount"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the volume should be automatically mounted</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_activation_root"> + <callback name="get_activation_root"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the activation root of @volume + or %NULL. Use g_object_unref() to free.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject_with_operation"> + <callback name="eject_with_operation"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags affecting the unmount if required for eject</doc> + <type name="MountUnmountFlags" c:type="GMountUnmountFlags"/> + </parameter> + <parameter name="mount_operation" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GMountOperation or %NULL to + avoid user interaction</doc> + <type name="MountOperation" c:type="GMountOperation*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5"> + <doc xml:space="preserve">a #GAsyncReadyCallback, or %NULL</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="5"> + <doc xml:space="preserve">user data passed to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="eject_with_operation_finish"> + <callback name="eject_with_operation_finish" throws="1"> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the volume was successfully ejected. %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_sort_key"> + <callback name="get_sort_key"> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">Sorting key for @volume or %NULL if no such key is available</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_symbolic_icon"> + <callback name="get_symbolic_icon"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon. + The returned object should be unreffed with g_object_unref() + when no longer needed.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume</doc> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="VolumeMonitor" c:symbol-prefix="volume_monitor" c:type="GVolumeMonitor" parent="GObject.Object" glib:type-name="GVolumeMonitor" glib:get-type="g_volume_monitor_get_type" glib:type-struct="VolumeMonitorClass"> + <doc xml:space="preserve">#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.</doc> + <function name="adopt_orphan_mount" c:identifier="g_volume_monitor_adopt_orphan_mount" deprecated="1" deprecated-version="2.20"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">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.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the #GVolume object that is the parent for @mount or %NULL +if no wants to adopt the #GMount.</doc> + <type name="Volume" c:type="GVolume*"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount object to find a parent for</doc> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </function> + <function name="get" c:identifier="g_volume_monitor_get"> + <doc xml:space="preserve">Gets the volume monitor used by gio.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a reference to the #GVolumeMonitor used by gio. Call + g_object_unref() when done with it.</doc> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </return-value> + </function> + <virtual-method name="drive_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + <parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="drive_connected"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + <parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="drive_disconnected"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + <parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="drive_eject_button"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + <parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="drive_stop_button"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + <parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_connected_drives" invoker="get_connected_drives"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GList of connected #GDrive objects.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="Drive"/> + </type> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolumeMonitor.</doc> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_mount_for_uuid" invoker="get_mount_for_uuid"> + <doc xml:space="preserve">Finds a #GMount object by its UUID (see g_mount_get_uuid())</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GMount or %NULL if no such mount is available. + Free the returned object with g_object_unref().</doc> + <type name="Mount" c:type="GMount*"/> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolumeMonitor.</doc> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + <parameter name="uuid" transfer-ownership="none"> + <doc xml:space="preserve">the UUID to look for</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_mounts" invoker="get_mounts"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GList of #GMount objects.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="Mount"/> + </type> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolumeMonitor.</doc> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="get_volume_for_uuid" invoker="get_volume_for_uuid"> + <doc xml:space="preserve">Finds a #GVolume object by its UUID (see g_volume_get_uuid())</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GVolume or %NULL if no such volume is available. + Free the returned object with g_object_unref().</doc> + <type name="Volume" c:type="GVolume*"/> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolumeMonitor.</doc> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + <parameter name="uuid" transfer-ownership="none"> + <doc xml:space="preserve">the UUID to look for</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_volumes" invoker="get_volumes"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GList of #GVolume objects.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="Volume"/> + </type> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolumeMonitor.</doc> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="mount_added"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + <parameter name="mount" transfer-ownership="none"> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="mount_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + <parameter name="mount" transfer-ownership="none"> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="mount_pre_unmount"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + <parameter name="mount" transfer-ownership="none"> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="mount_removed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + <parameter name="mount" transfer-ownership="none"> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="volume_added"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + <parameter name="volume" transfer-ownership="none"> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="volume_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + <parameter name="volume" transfer-ownership="none"> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="volume_removed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + <parameter name="volume" transfer-ownership="none"> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </virtual-method> + <method name="get_connected_drives" c:identifier="g_volume_monitor_get_connected_drives"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GList of connected #GDrive objects.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="Drive"/> + </type> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolumeMonitor.</doc> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_mount_for_uuid" c:identifier="g_volume_monitor_get_mount_for_uuid"> + <doc xml:space="preserve">Finds a #GMount object by its UUID (see g_mount_get_uuid())</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GMount or %NULL if no such mount is available. + Free the returned object with g_object_unref().</doc> + <type name="Mount" c:type="GMount*"/> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolumeMonitor.</doc> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + <parameter name="uuid" transfer-ownership="none"> + <doc xml:space="preserve">the UUID to look for</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_mounts" c:identifier="g_volume_monitor_get_mounts"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GList of #GMount objects.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="Mount"/> + </type> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolumeMonitor.</doc> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_volume_for_uuid" c:identifier="g_volume_monitor_get_volume_for_uuid"> + <doc xml:space="preserve">Finds a #GVolume object by its UUID (see g_volume_get_uuid())</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GVolume or %NULL if no such volume is available. + Free the returned object with g_object_unref().</doc> + <type name="Volume" c:type="GVolume*"/> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolumeMonitor.</doc> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + <parameter name="uuid" transfer-ownership="none"> + <doc xml:space="preserve">the UUID to look for</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_volumes" c:identifier="g_volume_monitor_get_volumes"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GList of #GVolume objects.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="Volume"/> + </type> + </return-value> + <parameters> + <instance-parameter name="volume_monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolumeMonitor.</doc> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </instance-parameter> + </parameters> + </method> + <field name="parent_instance"> + <type name="GObject.Object" c:type="GObject"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <glib:signal name="drive-changed" when="last"> + <doc xml:space="preserve">Emitted when a drive changes.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">the drive that changed</doc> + <type name="Drive"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="drive-connected" when="last"> + <doc xml:space="preserve">Emitted when a drive is connected to the system.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive that was connected.</doc> + <type name="Drive"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="drive-disconnected" when="last"> + <doc xml:space="preserve">Emitted when a drive is disconnected from the system.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">a #GDrive that was disconnected.</doc> + <type name="Drive"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="drive-eject-button" when="last" version="2.18"> + <doc xml:space="preserve">Emitted when the eject button is pressed on @drive.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">the drive where the eject button was pressed</doc> + <type name="Drive"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="drive-stop-button" when="last" version="2.22"> + <doc xml:space="preserve">Emitted when the stop button is pressed on @drive.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="drive" transfer-ownership="none"> + <doc xml:space="preserve">the drive where the stop button was pressed</doc> + <type name="Drive"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="mount-added" when="last"> + <doc xml:space="preserve">Emitted when a mount is added.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount that was added.</doc> + <type name="Mount"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="mount-changed" when="last"> + <doc xml:space="preserve">Emitted when a mount changes.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount that changed.</doc> + <type name="Mount"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="mount-pre-unmount" when="last"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount that is being unmounted.</doc> + <type name="Mount"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="mount-removed" when="last"> + <doc xml:space="preserve">Emitted when a mount is removed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <doc xml:space="preserve">a #GMount that was removed.</doc> + <type name="Mount"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="volume-added" when="last"> + <doc xml:space="preserve">Emitted when a mountable volume is added to the system.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume that was added.</doc> + <type name="Volume"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="volume-changed" when="last"> + <doc xml:space="preserve">Emitted when mountable volume is changed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume that changed.</doc> + <type name="Volume"/> + </parameter> + </parameters> + </glib:signal> + <glib:signal name="volume-removed" when="last"> + <doc xml:space="preserve">Emitted when a mountable volume is removed from the system.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolume that was removed.</doc> + <type name="Volume"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="VolumeMonitorClass" c:type="GVolumeMonitorClass" glib:is-gtype-struct-for="VolumeMonitor"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="volume_added"> + <callback name="volume_added"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + <parameter name="volume" transfer-ownership="none"> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="volume_removed"> + <callback name="volume_removed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + <parameter name="volume" transfer-ownership="none"> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="volume_changed"> + <callback name="volume_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + <parameter name="volume" transfer-ownership="none"> + <type name="Volume" c:type="GVolume*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="mount_added"> + <callback name="mount_added"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + <parameter name="mount" transfer-ownership="none"> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="mount_removed"> + <callback name="mount_removed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + <parameter name="mount" transfer-ownership="none"> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="mount_pre_unmount"> + <callback name="mount_pre_unmount"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + <parameter name="mount" transfer-ownership="none"> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="mount_changed"> + <callback name="mount_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + <parameter name="mount" transfer-ownership="none"> + <type name="Mount" c:type="GMount*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="drive_connected"> + <callback name="drive_connected"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + <parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="drive_disconnected"> + <callback name="drive_disconnected"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + <parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="drive_changed"> + <callback name="drive_changed"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + <parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="is_supported"> + <callback name="is_supported"> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + </callback> + </field> + <field name="get_connected_drives"> + <callback name="get_connected_drives"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GList of connected #GDrive objects.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="Drive"/> + </type> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolumeMonitor.</doc> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_volumes"> + <callback name="get_volumes"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GList of #GVolume objects.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="Volume"/> + </type> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolumeMonitor.</doc> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_mounts"> + <callback name="get_mounts"> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GList of #GMount objects.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="Mount"/> + </type> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolumeMonitor.</doc> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_volume_for_uuid"> + <callback name="get_volume_for_uuid"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GVolume or %NULL if no such volume is available. + Free the returned object with g_object_unref().</doc> + <type name="Volume" c:type="GVolume*"/> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolumeMonitor.</doc> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + <parameter name="uuid" transfer-ownership="none"> + <doc xml:space="preserve">the UUID to look for</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_mount_for_uuid"> + <callback name="get_mount_for_uuid"> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GMount or %NULL if no such mount is available. + Free the returned object with g_object_unref().</doc> + <type name="Mount" c:type="GMount*"/> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <doc xml:space="preserve">a #GVolumeMonitor.</doc> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + <parameter name="uuid" transfer-ownership="none"> + <doc xml:space="preserve">the UUID to look for</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="adopt_orphan_mount" introspectable="0"> + <callback name="adopt_orphan_mount" introspectable="0"> + <return-value> + <type name="Volume" c:type="GVolume*"/> + </return-value> + <parameters> + <parameter name="mount" transfer-ownership="none"> + <type name="Mount" c:type="GMount*"/> + </parameter> + <parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="drive_eject_button"> + <callback name="drive_eject_button"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + <parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="drive_stop_button"> + <callback name="drive_stop_button"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="volume_monitor" transfer-ownership="none"> + <type name="VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + <parameter name="drive" transfer-ownership="none"> + <type name="Drive" c:type="GDrive*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved6" introspectable="0"> + <callback name="_g_reserved6"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <function-macro name="ZLIB_COMPRESSOR" c:identifier="G_ZLIB_COMPRESSOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ZLIB_COMPRESSOR_CLASS" c:identifier="G_ZLIB_COMPRESSOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ZLIB_COMPRESSOR_GET_CLASS" c:identifier="G_ZLIB_COMPRESSOR_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ZLIB_DECOMPRESSOR" c:identifier="G_ZLIB_DECOMPRESSOR" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ZLIB_DECOMPRESSOR_CLASS" c:identifier="G_ZLIB_DECOMPRESSOR_CLASS" introspectable="0"> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ZLIB_DECOMPRESSOR_GET_CLASS" c:identifier="G_ZLIB_DECOMPRESSOR_GET_CLASS" introspectable="0"> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <class name="ZlibCompressor" c:symbol-prefix="zlib_compressor" c:type="GZlibCompressor" parent="GObject.Object" glib:type-name="GZlibCompressor" glib:get-type="g_zlib_compressor_get_type" glib:type-struct="ZlibCompressorClass"> + <doc xml:space="preserve">Zlib decompression</doc> + <implements name="Converter"/> + <constructor name="new" c:identifier="g_zlib_compressor_new" version="2.24"> + <doc xml:space="preserve">Creates a new #GZlibCompressor.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GZlibCompressor</doc> + <type name="ZlibCompressor" c:type="GZlibCompressor*"/> + </return-value> + <parameters> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">The format to use for the compressed data</doc> + <type name="ZlibCompressorFormat" c:type="GZlibCompressorFormat"/> + </parameter> + <parameter name="level" transfer-ownership="none"> + <doc xml:space="preserve">compression level (0-9), -1 for default</doc> + <type name="gint" c:type="int"/> + </parameter> + </parameters> + </constructor> + <method name="get_file_info" c:identifier="g_zlib_compressor_get_file_info" version="2.26"> + <doc xml:space="preserve">Returns the #GZlibCompressor:file-info property.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a #GFileInfo, or %NULL</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="compressor" transfer-ownership="none"> + <doc xml:space="preserve">a #GZlibCompressor</doc> + <type name="ZlibCompressor" c:type="GZlibCompressor*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_file_info" c:identifier="g_zlib_compressor_set_file_info" version="2.26"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="compressor" transfer-ownership="none"> + <doc xml:space="preserve">a #GZlibCompressor</doc> + <type name="ZlibCompressor" c:type="GZlibCompressor*"/> + </instance-parameter> + <parameter name="file_info" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GFileInfo</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </parameter> + </parameters> + </method> + <property name="file-info" version="2.26" writable="1" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="FileInfo"/> + </property> + <property name="format" writable="1" construct-only="1" transfer-ownership="none"> + <type name="ZlibCompressorFormat"/> + </property> + <property name="level" writable="1" construct-only="1" transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </property> + </class> + <record name="ZlibCompressorClass" c:type="GZlibCompressorClass" glib:is-gtype-struct-for="ZlibCompressor"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <enumeration name="ZlibCompressorFormat" version="2.24" glib:type-name="GZlibCompressorFormat" glib:get-type="g_zlib_compressor_format_get_type" c:type="GZlibCompressorFormat"> + <doc xml:space="preserve">Used to select the type of data format to use for #GZlibDecompressor +and #GZlibCompressor.</doc> + <member name="zlib" value="0" c:identifier="G_ZLIB_COMPRESSOR_FORMAT_ZLIB" glib:nick="zlib"> + <doc xml:space="preserve">deflate compression with zlib header</doc> + </member> + <member name="gzip" value="1" c:identifier="G_ZLIB_COMPRESSOR_FORMAT_GZIP" glib:nick="gzip"> + <doc xml:space="preserve">gzip file format</doc> + </member> + <member name="raw" value="2" c:identifier="G_ZLIB_COMPRESSOR_FORMAT_RAW" glib:nick="raw"> + <doc xml:space="preserve">deflate compression with no header</doc> + </member> + </enumeration> + <class name="ZlibDecompressor" c:symbol-prefix="zlib_decompressor" c:type="GZlibDecompressor" parent="GObject.Object" glib:type-name="GZlibDecompressor" glib:get-type="g_zlib_decompressor_get_type" glib:type-struct="ZlibDecompressorClass"> + <doc xml:space="preserve">Zlib decompression</doc> + <implements name="Converter"/> + <constructor name="new" c:identifier="g_zlib_decompressor_new" version="2.24"> + <doc xml:space="preserve">Creates a new #GZlibDecompressor.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GZlibDecompressor</doc> + <type name="ZlibDecompressor" c:type="GZlibDecompressor*"/> + </return-value> + <parameters> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">The format to use for the compressed data</doc> + <type name="ZlibCompressorFormat" c:type="GZlibCompressorFormat"/> + </parameter> + </parameters> + </constructor> + <method name="get_file_info" c:identifier="g_zlib_decompressor_get_file_info" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a #GFileInfo, or %NULL</doc> + <type name="FileInfo" c:type="GFileInfo*"/> + </return-value> + <parameters> + <instance-parameter name="decompressor" transfer-ownership="none"> + <doc xml:space="preserve">a #GZlibDecompressor</doc> + <type name="ZlibDecompressor" c:type="GZlibDecompressor*"/> + </instance-parameter> + </parameters> + </method> + <property name="file-info" version="2.26" transfer-ownership="none"> + <doc xml:space="preserve">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.</doc> + <type name="FileInfo"/> + </property> + <property name="format" writable="1" construct-only="1" transfer-ownership="none"> + <type name="ZlibCompressorFormat"/> + </property> + </class> + <record name="ZlibDecompressorClass" c:type="GZlibDecompressorClass" glib:is-gtype-struct-for="ZlibDecompressor"> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <function name="action_name_is_valid" c:identifier="g_action_name_is_valid" moved-to="Action.name_is_valid" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @action_name is valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">a potential action name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="action_parse_detailed_name" c:identifier="g_action_parse_detailed_name" moved-to="Action.parse_detailed_name" version="2.38" throws="1"> + <doc xml:space="preserve">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 '.'.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if successful, else %FALSE with @error set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="detailed_name" transfer-ownership="none"> + <doc xml:space="preserve">a detailed action name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="action_name" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the action name</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="target_value" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">the target value, or %NULL for no target</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + </parameters> + </function> + <function name="action_print_detailed_name" c:identifier="g_action_print_detailed_name" moved-to="Action.print_detailed_name" version="2.38"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a detailed format string</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="action_name" transfer-ownership="none"> + <doc xml:space="preserve">a valid action name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="target_value" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GVariant target value, or %NULL</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <function name="app_info_create_from_commandline" c:identifier="g_app_info_create_from_commandline" moved-to="AppInfo.create_from_commandline" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">new #GAppInfo for given command.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </return-value> + <parameters> + <parameter name="commandline" transfer-ownership="none"> + <doc xml:space="preserve">the commandline to use</doc> + <type name="filename" c:type="const char*"/> + </parameter> + <parameter name="application_name" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the application name, or %NULL to use @commandline</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">flags that can specify details of the created #GAppInfo</doc> + <type name="AppInfoCreateFlags" c:type="GAppInfoCreateFlags"/> + </parameter> + </parameters> + </function> + <function name="app_info_get_all" c:identifier="g_app_info_get_all" moved-to="AppInfo.get_all"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated #GList of references to #GAppInfos.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="AppInfo"/> + </type> + </return-value> + </function> + <function name="app_info_get_all_for_type" c:identifier="g_app_info_get_all_for_type" moved-to="AppInfo.get_all_for_type"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GList of #GAppInfos + for given @content_type or %NULL on error.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="AppInfo"/> + </type> + </return-value> + <parameters> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">the content type to find a #GAppInfo for</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="app_info_get_default_for_type" c:identifier="g_app_info_get_default_for_type" moved-to="AppInfo.get_default_for_type"> + <doc xml:space="preserve">Gets the default #GAppInfo for a given content type.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">#GAppInfo for given @content_type or + %NULL on error.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </return-value> + <parameters> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">the content type to find a #GAppInfo for</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="must_support_uris" transfer-ownership="none"> + <doc xml:space="preserve">if %TRUE, the #GAppInfo is expected to + support URIs</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </function> + <function name="app_info_get_default_for_uri_scheme" c:identifier="g_app_info_get_default_for_uri_scheme" moved-to="AppInfo.get_default_for_uri_scheme"> + <doc xml:space="preserve">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".</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">#GAppInfo for given @uri_scheme or + %NULL on error.</doc> + <type name="AppInfo" c:type="GAppInfo*"/> + </return-value> + <parameters> + <parameter name="uri_scheme" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a URI scheme.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="app_info_get_fallback_for_type" c:identifier="g_app_info_get_fallback_for_type" moved-to="AppInfo.get_fallback_for_type" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GList of #GAppInfos + for given @content_type or %NULL on error.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="AppInfo"/> + </type> + </return-value> + <parameters> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">the content type to find a #GAppInfo for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="app_info_get_recommended_for_type" c:identifier="g_app_info_get_recommended_for_type" moved-to="AppInfo.get_recommended_for_type" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GList of #GAppInfos + for given @content_type or %NULL on error.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="AppInfo"/> + </type> + </return-value> + <parameters> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">the content type to find a #GAppInfo for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="app_info_launch_default_for_uri" c:identifier="g_app_info_launch_default_for_uri" moved-to="AppInfo.launch_default_for_uri" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE on error.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">the uri to show</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GAppLaunchContext</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + </parameters> + </function> + <function name="app_info_launch_default_for_uri_async" c:identifier="g_app_info_launch_default_for_uri_async" moved-to="AppInfo.launch_default_for_uri_async" version="2.50"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">the uri to show</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="context" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">an optional #GAppLaunchContext</doc> + <type name="AppLaunchContext" c:type="GAppLaunchContext*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="4"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is done</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="app_info_launch_default_for_uri_finish" c:identifier="g_app_info_launch_default_for_uri_finish" moved-to="AppInfo.launch_default_for_uri_finish" version="2.50" throws="1"> + <doc xml:space="preserve">Finishes an asynchronous launch-default-for-uri operation.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the launch was successful, %FALSE if @error is set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </function> + <function name="app_info_reset_type_associations" c:identifier="g_app_info_reset_type_associations" moved-to="AppInfo.reset_type_associations" version="2.20"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="content_type" transfer-ownership="none"> + <doc xml:space="preserve">a content type</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="async_initable_newv_async" c:identifier="g_async_initable_newv_async" moved-to="AsyncInitable.newv_async" version="2.22" deprecated="1" deprecated-version="2.54"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_object_new_with_properties() and +g_async_initable_init_async() instead. See #GParameter for more information.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType supporting #GAsyncInitable.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_parameters" transfer-ownership="none"> + <doc xml:space="preserve">the number of parameters in @parameters</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="parameters" transfer-ownership="none"> + <doc xml:space="preserve">the parameters to use to construct the object</doc> + <type name="GObject.Parameter" c:type="GParameter*"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] of the operation</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="6"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the initialization is + finished</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to callback function</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="bus_get" c:identifier="g_bus_get" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="bus_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GBusType</doc> + <type name="BusType" c:type="GBusType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">a #GAsyncReadyCallback to call when the request is satisfied</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="bus_get_finish" c:identifier="g_bus_get_finish" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GDBusConnection or %NULL if @error is set. + Free with g_object_unref().</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </return-value> + <parameters> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">a #GAsyncResult obtained from the #GAsyncReadyCallback passed + to g_bus_get()</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </function> + <function name="bus_get_sync" c:identifier="g_bus_get_sync" version="2.26" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GDBusConnection or %NULL if @error is set. + Free with g_object_unref().</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </return-value> + <parameters> + <parameter name="bus_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GBusType</doc> + <type name="BusType" c:type="GBusType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="bus_own_name" c:identifier="g_bus_own_name" shadowed-by="bus_own_name_with_closures" version="2.26" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an identifier (never 0) that can be used with + g_bus_unown_name() to stop owning the name.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="bus_type" transfer-ownership="none"> + <doc xml:space="preserve">the type of bus to own a name on</doc> + <type name="BusType" c:type="GBusType"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the well-known name to own</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of flags from the #GBusNameOwnerFlags enumeration</doc> + <type name="BusNameOwnerFlags" c:type="GBusNameOwnerFlags"/> + </parameter> + <parameter name="bus_acquired_handler" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">handler to invoke when connected to the bus of type @bus_type or %NULL</doc> + <type name="BusAcquiredCallback" c:type="GBusAcquiredCallback"/> + </parameter> + <parameter name="name_acquired_handler" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">handler to invoke when @name is acquired or %NULL</doc> + <type name="BusNameAcquiredCallback" c:type="GBusNameAcquiredCallback"/> + </parameter> + <parameter name="name_lost_handler" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="6" destroy="7"> + <doc xml:space="preserve">handler to invoke when @name is lost or %NULL</doc> + <type name="BusNameLostCallback" c:type="GBusNameLostCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to handlers</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="user_data_free_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">function for freeing @user_data or %NULL</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="bus_own_name_on_connection" c:identifier="g_bus_own_name_on_connection" shadowed-by="bus_own_name_on_connection_with_closures" version="2.26" introspectable="0"> + <doc xml:space="preserve">Like g_bus_own_name() but takes a #GDBusConnection instead of a +#GBusType.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an identifier (never 0) that can be used with + g_bus_unown_name() to stop owning the name</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the well-known name to own</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of flags from the #GBusNameOwnerFlags enumeration</doc> + <type name="BusNameOwnerFlags" c:type="GBusNameOwnerFlags"/> + </parameter> + <parameter name="name_acquired_handler" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">handler to invoke when @name is acquired or %NULL</doc> + <type name="BusNameAcquiredCallback" c:type="GBusNameAcquiredCallback"/> + </parameter> + <parameter name="name_lost_handler" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="5" destroy="6"> + <doc xml:space="preserve">handler to invoke when @name is lost or %NULL</doc> + <type name="BusNameLostCallback" c:type="GBusNameLostCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data to pass to handlers</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="user_data_free_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">function for freeing @user_data or %NULL</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="bus_own_name_on_connection_with_closures" c:identifier="g_bus_own_name_on_connection_with_closures" shadows="bus_own_name_on_connection" version="2.26"> + <doc xml:space="preserve">Version of g_bus_own_name_on_connection() using closures instead of +callbacks for easier binding in other languages.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an identifier (never 0) that can be used with + g_bus_unown_name() to stop owning the name.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">a #GDBusConnection</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the well-known name to own</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of flags from the #GBusNameOwnerFlags enumeration</doc> + <type name="BusNameOwnerFlags" c:type="GBusNameOwnerFlags"/> + </parameter> + <parameter name="name_acquired_closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">#GClosure to invoke when @name is + acquired or %NULL</doc> + <type name="GObject.Closure" c:type="GClosure*"/> + </parameter> + <parameter name="name_lost_closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">#GClosure to invoke when @name is lost + or %NULL</doc> + <type name="GObject.Closure" c:type="GClosure*"/> + </parameter> + </parameters> + </function> + <function name="bus_own_name_with_closures" c:identifier="g_bus_own_name_with_closures" shadows="bus_own_name" version="2.26"> + <doc xml:space="preserve">Version of g_bus_own_name() using closures instead of callbacks for +easier binding in other languages.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">an identifier (never 0) that can be used with + g_bus_unown_name() to stop owning the name.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="bus_type" transfer-ownership="none"> + <doc xml:space="preserve">the type of bus to own a name on</doc> + <type name="BusType" c:type="GBusType"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the well-known name to own</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">a set of flags from the #GBusNameOwnerFlags enumeration</doc> + <type name="BusNameOwnerFlags" c:type="GBusNameOwnerFlags"/> + </parameter> + <parameter name="bus_acquired_closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">#GClosure to invoke when connected to + the bus of type @bus_type or %NULL</doc> + <type name="GObject.Closure" c:type="GClosure*"/> + </parameter> + <parameter name="name_acquired_closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">#GClosure to invoke when @name is + acquired or %NULL</doc> + <type name="GObject.Closure" c:type="GClosure*"/> + </parameter> + <parameter name="name_lost_closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">#GClosure to invoke when @name is lost or + %NULL</doc> + <type name="GObject.Closure" c:type="GClosure*"/> + </parameter> + </parameters> + </function> + <function name="bus_unown_name" c:identifier="g_bus_unown_name" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="owner_id" transfer-ownership="none"> + <doc xml:space="preserve">an identifier obtained from g_bus_own_name()</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="bus_unwatch_name" c:identifier="g_bus_unwatch_name" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="watcher_id" transfer-ownership="none"> + <doc xml:space="preserve">An identifier obtained from g_bus_watch_name()</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="bus_watch_name" c:identifier="g_bus_watch_name" shadowed-by="bus_watch_name_with_closures" version="2.26" introspectable="0"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">An identifier (never 0) that can be used with +g_bus_unwatch_name() to stop watching the name.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="bus_type" transfer-ownership="none"> + <doc xml:space="preserve">The type of bus to watch a name on.</doc> + <type name="BusType" c:type="GBusType"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">The name (well-known or unique) to watch.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GBusNameWatcherFlags enumeration.</doc> + <type name="BusNameWatcherFlags" c:type="GBusNameWatcherFlags"/> + </parameter> + <parameter name="name_appeared_handler" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Handler to invoke when @name is known to exist or %NULL.</doc> + <type name="BusNameAppearedCallback" c:type="GBusNameAppearedCallback"/> + </parameter> + <parameter name="name_vanished_handler" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="5" destroy="6"> + <doc xml:space="preserve">Handler to invoke when @name is known to not exist or %NULL.</doc> + <type name="BusNameVanishedCallback" c:type="GBusNameVanishedCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">User data to pass to handlers.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="user_data_free_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">Function for freeing @user_data or %NULL.</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="bus_watch_name_on_connection" c:identifier="g_bus_watch_name_on_connection" shadowed-by="bus_watch_name_on_connection_with_closures" version="2.26" introspectable="0"> + <doc xml:space="preserve">Like g_bus_watch_name() but takes a #GDBusConnection instead of a +#GBusType.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">An identifier (never 0) that can be used with +g_bus_unwatch_name() to stop watching the name.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">The name (well-known or unique) to watch.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GBusNameWatcherFlags enumeration.</doc> + <type name="BusNameWatcherFlags" c:type="GBusNameWatcherFlags"/> + </parameter> + <parameter name="name_appeared_handler" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Handler to invoke when @name is known to exist or %NULL.</doc> + <type name="BusNameAppearedCallback" c:type="GBusNameAppearedCallback"/> + </parameter> + <parameter name="name_vanished_handler" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="5" destroy="6"> + <doc xml:space="preserve">Handler to invoke when @name is known to not exist or %NULL.</doc> + <type name="BusNameVanishedCallback" c:type="GBusNameVanishedCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">User data to pass to handlers.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="user_data_free_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">Function for freeing @user_data or %NULL.</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </function> + <function name="bus_watch_name_on_connection_with_closures" c:identifier="g_bus_watch_name_on_connection_with_closures" shadows="bus_watch_name_on_connection" version="2.26"> + <doc xml:space="preserve">Version of g_bus_watch_name_on_connection() using closures instead of callbacks for +easier binding in other languages.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">An identifier (never 0) that can be used with +g_bus_unwatch_name() to stop watching the name.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="connection" transfer-ownership="none"> + <doc xml:space="preserve">A #GDBusConnection.</doc> + <type name="DBusConnection" c:type="GDBusConnection*"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">The name (well-known or unique) to watch.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GBusNameWatcherFlags enumeration.</doc> + <type name="BusNameWatcherFlags" c:type="GBusNameWatcherFlags"/> + </parameter> + <parameter name="name_appeared_closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">#GClosure to invoke when @name is known +to exist or %NULL.</doc> + <type name="GObject.Closure" c:type="GClosure*"/> + </parameter> + <parameter name="name_vanished_closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">#GClosure to invoke when @name is known +to not exist or %NULL.</doc> + <type name="GObject.Closure" c:type="GClosure*"/> + </parameter> + </parameters> + </function> + <function name="bus_watch_name_with_closures" c:identifier="g_bus_watch_name_with_closures" shadows="bus_watch_name" version="2.26"> + <doc xml:space="preserve">Version of g_bus_watch_name() using closures instead of callbacks for +easier binding in other languages.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">An identifier (never 0) that can be used with +g_bus_unwatch_name() to stop watching the name.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="bus_type" transfer-ownership="none"> + <doc xml:space="preserve">The type of bus to watch a name on.</doc> + <type name="BusType" c:type="GBusType"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">The name (well-known or unique) to watch.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve">Flags from the #GBusNameWatcherFlags enumeration.</doc> + <type name="BusNameWatcherFlags" c:type="GBusNameWatcherFlags"/> + </parameter> + <parameter name="name_appeared_closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">#GClosure to invoke when @name is known +to exist or %NULL.</doc> + <type name="GObject.Closure" c:type="GClosure*"/> + </parameter> + <parameter name="name_vanished_closure" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">#GClosure to invoke when @name is known +to not exist or %NULL.</doc> + <type name="GObject.Closure" c:type="GClosure*"/> + </parameter> + </parameters> + </function> + <function name="content_type_can_be_executable" c:identifier="g_content_type_can_be_executable"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the file type corresponds to a type that + can be executable, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a content type string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="content_type_equals" c:identifier="g_content_type_equals"> + <doc xml:space="preserve">Compares two content types for equality.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the two strings are identical or equivalent, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="type1" transfer-ownership="none"> + <doc xml:space="preserve">a content type string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="type2" transfer-ownership="none"> + <doc xml:space="preserve">a content type string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="content_type_from_mime_type" c:identifier="g_content_type_from_mime_type" version="2.18"> + <doc xml:space="preserve">Tries to find a content type based on the mime type name.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">Newly allocated string with content type or + %NULL. Free with g_free()</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="mime_type" transfer-ownership="none"> + <doc xml:space="preserve">a mime type string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="content_type_get_description" c:identifier="g_content_type_get_description"> + <doc xml:space="preserve">Gets the human readable description of the content type.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a short description of the content type @type. Free the + returned string with g_free()</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a content type string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="content_type_get_generic_icon_name" c:identifier="g_content_type_get_generic_icon_name" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the registered generic icon name for the given @type, + or %NULL if unknown. Free with g_free()</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a content type string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="content_type_get_icon" c:identifier="g_content_type_get_icon"> + <doc xml:space="preserve">Gets the icon for a content type.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GIcon corresponding to the content type. Free the returned + object with g_object_unref()</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a content type string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="content_type_get_mime_dirs" c:identifier="g_content_type_get_mime_dirs" version="2.60"> + <doc xml:space="preserve">Get the list of directories which MIME data is loaded from. See +g_content_type_set_mime_dirs() for details.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%NULL-terminated list of + directories to load MIME data from, including any `mime/` subdirectory, + and with the first directory to try listed first</doc> + <array c:type="const gchar* const*"> + <type name="utf8"/> + </array> + </return-value> + </function> + <function name="content_type_get_mime_type" c:identifier="g_content_type_get_mime_type"> + <doc xml:space="preserve">Gets the mime type for the content type, if one is registered.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">the registered mime type for the + given @type, or %NULL if unknown; free with g_free().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a content type string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="content_type_get_symbolic_icon" c:identifier="g_content_type_get_symbolic_icon" version="2.34"> + <doc xml:space="preserve">Gets the symbolic icon for a content type.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">symbolic #GIcon corresponding to the content type. + Free the returned object with g_object_unref()</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a content type string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="content_type_guess" c:identifier="g_content_type_guess"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a string indicating a guessed content type for the + given data. Free with g_free()</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a string, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a stream of data, or %NULL</doc> + <array length="2" zero-terminated="0" c:type="const guchar*"> + <type name="guint8" c:type="guchar"/> + </array> + </parameter> + <parameter name="data_size" transfer-ownership="none"> + <doc xml:space="preserve">the size of @data</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="result_uncertain" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">return location for the certainty + of the result, or %NULL</doc> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + </parameters> + </function> + <function name="content_type_guess_for_tree" c:identifier="g_content_type_guess_for_tree" version="2.18"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an %NULL-terminated + array of zero or more content types. Free with g_strfreev()</doc> + <array c:type="gchar**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="root" transfer-ownership="none"> + <doc xml:space="preserve">the root of the tree to guess a type for</doc> + <type name="File" c:type="GFile*"/> + </parameter> + </parameters> + </function> + <function name="content_type_is_a" c:identifier="g_content_type_is_a"> + <doc xml:space="preserve">Determines if @type is a subset of @supertype.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @type is a kind of @supertype, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a content type string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="supertype" transfer-ownership="none"> + <doc xml:space="preserve">a content type string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="content_type_is_mime_type" c:identifier="g_content_type_is_mime_type" version="2.52"> + <doc xml:space="preserve">Determines if @type is a subset of @mime_type. +Convenience wrapper around g_content_type_is_a().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @type is a kind of @mime_type, + %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a content type string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="mime_type" transfer-ownership="none"> + <doc xml:space="preserve">a mime type string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="content_type_is_unknown" c:identifier="g_content_type_is_unknown"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the type is the unknown type.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">a content type string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="content_type_set_mime_dirs" c:identifier="g_content_type_set_mime_dirs" version="2.60"> + <doc xml:space="preserve">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 (); +]|</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="dirs" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">%NULL-terminated list of + directories to load MIME data from, including any `mime/` subdirectory, + and with the first directory to try listed first</doc> + <array c:type="const gchar* const*"> + <type name="utf8" c:type="gchar*"/> + </array> + </parameter> + </parameters> + </function> + <function name="content_types_get_registered" c:identifier="g_content_types_get_registered"> + <doc xml:space="preserve">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)`.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">list of the registered + content types</doc> + <type name="GLib.List" c:type="GList*"> + <type name="utf8"/> + </type> + </return-value> + </function> + <function name="dbus_address_escape_value" c:identifier="g_dbus_address_escape_value" version="2.36"> + <doc xml:space="preserve">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`.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a copy of @string with all + non-optionally-escaped bytes escaped</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">an unescaped string to be included in a D-Bus address + as the value in a key-value pair</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="dbus_address_get_for_bus_sync" c:identifier="g_dbus_address_get_for_bus_sync" version="2.26" throws="1"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a valid D-Bus address string for @bus_type or + %NULL if @error is set</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="bus_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GBusType</doc> + <type name="BusType" c:type="GBusType"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GCancellable or %NULL</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="dbus_address_get_stream" c:identifier="g_dbus_address_get_stream" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">A valid D-Bus address.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3"> + <doc xml:space="preserve">A #GAsyncReadyCallback to call when the request is satisfied.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Data to pass to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="dbus_address_get_stream_finish" c:identifier="g_dbus_address_get_stream_finish" version="2.26" throws="1"> + <doc xml:space="preserve">Finishes an operation started with g_dbus_address_get_stream(). + +A server is not required to set a GUID, so @out_guid may be set to %NULL +even on success.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GIOStream or %NULL if @error is set.</doc> + <type name="IOStream" c:type="GIOStream*"/> + </return-value> + <parameters> + <parameter name="res" transfer-ownership="none"> + <doc xml:space="preserve">A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream().</doc> + <type name="AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="out_guid" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">%NULL or return location to store the GUID extracted from @address, if any.</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + </parameters> + </function> + <function name="dbus_address_get_stream_sync" c:identifier="g_dbus_address_get_stream_sync" version="2.26" throws="1"> + <doc xml:space="preserve">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). + +A server is not required to set a GUID, so @out_guid may be set to %NULL +even on success. + +This is a synchronous failable function. See +g_dbus_address_get_stream() for the asynchronous version.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GIOStream or %NULL if @error is set.</doc> + <type name="IOStream" c:type="GIOStream*"/> + </return-value> + <parameters> + <parameter name="address" transfer-ownership="none"> + <doc xml:space="preserve">A valid D-Bus address.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="out_guid" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1"> + <doc xml:space="preserve">%NULL or return location to store the GUID extracted from @address, if any.</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A #GCancellable or %NULL.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="dbus_annotation_info_lookup" c:identifier="g_dbus_annotation_info_lookup" moved-to="DBusAnnotationInfo.lookup" version="2.26"> + <doc xml:space="preserve">Looks up the value of an annotation. + +The cost of this function is O(n) in number of annotations.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">The value or %NULL if not found. Do not free, it is owned by @annotations.</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="annotations" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">A %NULL-terminated array of annotations or %NULL.</doc> + <array c:type="GDBusAnnotationInfo**"> + <type name="DBusAnnotationInfo" c:type="GDBusAnnotationInfo*"/> + </array> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">The name of the annotation to look up.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="dbus_error_encode_gerror" c:identifier="g_dbus_error_encode_gerror" moved-to="DBusError.encode_gerror" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A D-Bus error name (never %NULL). + Free with g_free().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">A #GError.</doc> + <type name="GLib.Error" c:type="const GError*"/> + </parameter> + </parameters> + </function> + <function name="dbus_error_get_remote_error" c:identifier="g_dbus_error_get_remote_error" moved-to="DBusError.get_remote_error" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">an allocated string or %NULL if the + D-Bus error name could not be found. Free with g_free().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">a #GError</doc> + <type name="GLib.Error" c:type="const GError*"/> + </parameter> + </parameters> + </function> + <function name="dbus_error_is_remote_error" c:identifier="g_dbus_error_is_remote_error" moved-to="DBusError.is_remote_error" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @error represents an error from a remote peer, +%FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">A #GError.</doc> + <type name="GLib.Error" c:type="const GError*"/> + </parameter> + </parameters> + </function> + <function name="dbus_error_new_for_dbus_error" c:identifier="g_dbus_error_new_for_dbus_error" moved-to="DBusError.new_for_dbus_error" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">An allocated #GError. Free with g_error_free().</doc> + <type name="GLib.Error" c:type="GError*"/> + </return-value> + <parameters> + <parameter name="dbus_error_name" transfer-ownership="none"> + <doc xml:space="preserve">D-Bus error name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="dbus_error_message" transfer-ownership="none"> + <doc xml:space="preserve">D-Bus error message.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="dbus_error_quark" c:identifier="g_dbus_error_quark" moved-to="DBusError.quark"> + <return-value transfer-ownership="none"> + <type name="GLib.Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="dbus_error_register_error" c:identifier="g_dbus_error_register_error" moved-to="DBusError.register_error" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the association was created, %FALSE if it already +exists.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="error_domain" transfer-ownership="none"> + <doc xml:space="preserve">A #GQuark for an error domain.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="error_code" transfer-ownership="none"> + <doc xml:space="preserve">An error code.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="dbus_error_name" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus error name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="dbus_error_register_error_domain" c:identifier="g_dbus_error_register_error_domain" moved-to="DBusError.register_error_domain" version="2.26"> + <doc xml:space="preserve">Helper function for associating a #GError error domain with D-Bus error names. + +While @quark_volatile has a `volatile` qualifier, this is a historical +artifact and the argument passed to it should not be `volatile`.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="error_domain_quark_name" transfer-ownership="none"> + <doc xml:space="preserve">The error domain name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="quark_volatile" transfer-ownership="none"> + <doc xml:space="preserve">A pointer where to store the #GQuark.</doc> + <type name="gsize" c:type="volatile gsize*"/> + </parameter> + <parameter name="entries" transfer-ownership="none"> + <doc xml:space="preserve">A pointer to @num_entries #GDBusErrorEntry struct items.</doc> + <array length="3" zero-terminated="0" c:type="const GDBusErrorEntry*"> + <type name="DBusErrorEntry" c:type="GDBusErrorEntry"/> + </array> + </parameter> + <parameter name="num_entries" transfer-ownership="none"> + <doc xml:space="preserve">Number of items to register.</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="dbus_error_strip_remote_error" c:identifier="g_dbus_error_strip_remote_error" moved-to="DBusError.strip_remote_error" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if information was stripped, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">A #GError.</doc> + <type name="GLib.Error" c:type="GError*"/> + </parameter> + </parameters> + </function> + <function name="dbus_error_unregister_error" c:identifier="g_dbus_error_unregister_error" moved-to="DBusError.unregister_error" version="2.26"> + <doc xml:space="preserve">Destroys an association previously set up with g_dbus_error_register_error().</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the association was destroyed, %FALSE if it wasn't found.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="error_domain" transfer-ownership="none"> + <doc xml:space="preserve">A #GQuark for an error domain.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="error_code" transfer-ownership="none"> + <doc xml:space="preserve">An error code.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="dbus_error_name" transfer-ownership="none"> + <doc xml:space="preserve">A D-Bus error name.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="dbus_generate_guid" c:identifier="g_dbus_generate_guid" version="2.26"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A valid D-Bus GUID. Free with g_free().</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + </function> + <function name="dbus_gvalue_to_gvariant" c:identifier="g_dbus_gvalue_to_gvariant" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A #GVariant (never floating) of + #GVariantType @type holding the data from @gvalue or an empty #GVariant + in case of failure. Free with g_variant_unref().</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="gvalue" transfer-ownership="none"> + <doc xml:space="preserve">A #GValue to convert to a #GVariant</doc> + <type name="GObject.Value" c:type="const GValue*"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">A #GVariantType</doc> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </parameter> + </parameters> + </function> + <function name="dbus_gvariant_to_gvalue" c:identifier="g_dbus_gvariant_to_gvalue" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">A #GVariant.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="out_gvalue" direction="out" caller-allocates="1" transfer-ownership="none"> + <doc xml:space="preserve">Return location pointing to a zero-filled (uninitialized) #GValue.</doc> + <type name="GObject.Value" c:type="GValue*"/> + </parameter> + </parameters> + </function> + <function name="dbus_is_address" c:identifier="g_dbus_is_address" version="2.26"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @string is a valid D-Bus address, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">A string.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="dbus_is_guid" c:identifier="g_dbus_is_guid" version="2.26"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @string is a guid, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">The string to check.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="dbus_is_interface_name" c:identifier="g_dbus_is_interface_name" version="2.26"> + <doc xml:space="preserve">Checks if @string is a valid D-Bus interface name.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if valid, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">The string to check.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="dbus_is_member_name" c:identifier="g_dbus_is_member_name" version="2.26"> + <doc xml:space="preserve">Checks if @string is a valid D-Bus member (e.g. signal or method) name.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if valid, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">The string to check.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="dbus_is_name" c:identifier="g_dbus_is_name" version="2.26"> + <doc xml:space="preserve">Checks if @string is a valid D-Bus bus name (either unique or well-known).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if valid, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">The string to check.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="dbus_is_supported_address" c:identifier="g_dbus_is_supported_address" version="2.26" throws="1"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @string is a valid D-Bus address that is +supported by this library, %FALSE if @error is set.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">A string.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="dbus_is_unique_name" c:identifier="g_dbus_is_unique_name" version="2.26"> + <doc xml:space="preserve">Checks if @string is a valid D-Bus unique bus name.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if valid, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="string" transfer-ownership="none"> + <doc xml:space="preserve">The string to check.</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="dtls_client_connection_new" c:identifier="g_dtls_client_connection_new" moved-to="DtlsClientConnection.new" version="2.48" throws="1"> + <doc xml:space="preserve">Creates a new #GDtlsClientConnection wrapping @base_socket which is +assumed to communicate with the server identified by @server_identity.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new + #GDtlsClientConnection, or %NULL on error</doc> + <type name="DtlsClientConnection" c:type="GDatagramBased*"/> + </return-value> + <parameters> + <parameter name="base_socket" transfer-ownership="none"> + <doc xml:space="preserve">the #GDatagramBased to wrap</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </parameter> + <parameter name="server_identity" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected identity of the server</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + </parameters> + </function> + <function name="dtls_server_connection_new" c:identifier="g_dtls_server_connection_new" moved-to="DtlsServerConnection.new" version="2.48" throws="1"> + <doc xml:space="preserve">Creates a new #GDtlsServerConnection wrapping @base_socket.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new + #GDtlsServerConnection, or %NULL on error</doc> + <type name="DtlsServerConnection" c:type="GDatagramBased*"/> + </return-value> + <parameters> + <parameter name="base_socket" transfer-ownership="none"> + <doc xml:space="preserve">the #GDatagramBased to wrap</doc> + <type name="DatagramBased" c:type="GDatagramBased*"/> + </parameter> + <parameter name="certificate" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the default server certificate, or %NULL</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + </parameters> + </function> + <docsection name="extensionpoints"> + <doc xml:space="preserve">#GIOExtensionPoint provides a mechanism for modules to extend the +functionality of the library or application that loaded it in an +organized fashion. + +An extension point is identified by a name, and it may optionally +require that any implementation must be of a certain type (or derived +thereof). Use g_io_extension_point_register() to register an +extension point, and g_io_extension_point_set_required_type() to +set a required type. + +A module can implement an extension point by specifying the #GType +that implements the functionality. Additionally, each implementation +of an extension point has a name, and a priority. Use +g_io_extension_point_implement() to implement an extension point. + + |[<!-- language="C" --> + GIOExtensionPoint *ep; + + // Register an extension point + ep = g_io_extension_point_register ("my-extension-point"); + g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE); + ]| + + |[<!-- language="C" --> + // Implement an extension point + G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE) + g_io_extension_point_implement ("my-extension-point", + my_example_impl_get_type (), + "my-example", + 10); + ]| + + It is up to the code that registered the extension point how + it uses the implementations that have been associated with it. + Depending on the use case, it may use all implementations, or + only the one with the highest priority, or pick a specific + one by name. + + To avoid opening all modules just to find out what extension + points they implement, GIO makes use of a caching mechanism, + see [gio-querymodules][gio-querymodules]. + You are expected to run this command after installing a + GIO module. + + The `GIO_EXTRA_MODULES` environment variable can be used to + specify additional directories to automatically load modules + from. This environment variable has the same syntax as the + `PATH`. If two modules have the same base name in different + directories, then the latter one will be ignored. If additional + directories are specified GIO will load modules from the built-in + directory last.</doc> + </docsection> + <function name="file_new_for_commandline_arg" c:identifier="g_file_new_for_commandline_arg" moved-to="File.new_for_commandline_arg"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="arg" transfer-ownership="none"> + <doc xml:space="preserve">a command line string</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="file_new_for_commandline_arg_and_cwd" c:identifier="g_file_new_for_commandline_arg_and_cwd" moved-to="File.new_for_commandline_arg_and_cwd" version="2.36"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="arg" transfer-ownership="none"> + <doc xml:space="preserve">a command line string</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="cwd" transfer-ownership="none"> + <doc xml:space="preserve">the current working directory of the commandline</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="file_new_for_path" c:identifier="g_file_new_for_path" moved-to="File.new_for_path"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile for the given @path. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">a string containing a relative or absolute path. + The string must be encoded in the glib filename encoding.</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="file_new_for_uri" c:identifier="g_file_new_for_uri" moved-to="File.new_for_uri"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile for the given @uri. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve">a UTF-8 string containing a URI</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="file_new_tmp" c:identifier="g_file_new_tmp" moved-to="File.new_tmp" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile. + Free the returned object with g_object_unref().</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="tmpl" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">Template for the file + name, as in g_file_open_tmp(), or %NULL for a default template</doc> + <type name="filename" c:type="const char*"/> + </parameter> + <parameter name="iostream" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">on return, a #GFileIOStream for the created file</doc> + <type name="FileIOStream" c:type="GFileIOStream**"/> + </parameter> + </parameters> + </function> + <function name="file_parse_name" c:identifier="g_file_parse_name" moved-to="File.parse_name"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GFile.</doc> + <type name="File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="parse_name" transfer-ownership="none"> + <doc xml:space="preserve">a file name or path to be parsed</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <docsection name="gactiongroupexporter"> + <doc xml:space="preserve">These functions support exporting a #GActionGroup on D-Bus. +The D-Bus interface that is used is a private implementation +detail. + +To access an exported #GActionGroup remotely, use +g_dbus_action_group_get() to obtain a #GDBusActionGroup.</doc> + </docsection> + <docsection name="gcontenttype"> + <doc xml:space="preserve">A content type is a platform specific string that defines the type +of a file. On UNIX it is a +[MIME type](http://www.wikipedia.org/wiki/Internet_media_type) +like `text/plain` or `image/png`. +On Win32 it is an extension string like `.doc`, `.txt` or a perceived +string like `audio`. Such strings can be looked up in the registry at +`HKEY_CLASSES_ROOT`. +On macOS it is a [Uniform Type Identifier](https://en.wikipedia.org/wiki/Uniform_Type_Identifier) +such as `com.apple.application`.</doc> + </docsection> + <docsection name="gdbusaddress"> + <doc xml:space="preserve">Routines for working with D-Bus addresses. A D-Bus address is a string +like `unix:tmpdir=/tmp/my-app-name`. The exact format of addresses +is explained in detail in the +[D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#addresses). + +TCP D-Bus connections are supported, but accessing them via a proxy is +currently not supported.</doc> + </docsection> + <docsection name="gdbuserror"> + <doc xml:space="preserve">All facilities that return errors from remote methods (such as +g_dbus_connection_call_sync()) use #GError to represent both D-Bus +errors (e.g. errors returned from the other peer) and locally +in-process generated errors. + +To check if a returned #GError is an error from a remote peer, use +g_dbus_error_is_remote_error(). To get the actual D-Bus error name, +use g_dbus_error_get_remote_error(). Before presenting an error, +always use g_dbus_error_strip_remote_error(). + +In addition, facilities used to return errors to a remote peer also +use #GError. See g_dbus_method_invocation_return_error() for +discussion about how the D-Bus error name is set. + +Applications can associate a #GError error domain with a set of D-Bus errors in order to +automatically map from D-Bus errors to #GError and back. This +is typically done in the function returning the #GQuark for the +error domain: +|[<!-- language="C" --> +// foo-bar-error.h: + +#define FOO_BAR_ERROR (foo_bar_error_quark ()) +GQuark foo_bar_error_quark (void); + +typedef enum +{ + FOO_BAR_ERROR_FAILED, + FOO_BAR_ERROR_ANOTHER_ERROR, + FOO_BAR_ERROR_SOME_THIRD_ERROR, + FOO_BAR_N_ERRORS / *< skip >* / +} FooBarError; + +// foo-bar-error.c: + +static const GDBusErrorEntry foo_bar_error_entries[] = +{ + {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"}, + {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"}, + {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"}, +}; + +// Ensure that every error code has an associated D-Bus error name +G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS); + +GQuark +foo_bar_error_quark (void) +{ + static gsize quark = 0; + g_dbus_error_register_error_domain ("foo-bar-error-quark", + &quark, + foo_bar_error_entries, + G_N_ELEMENTS (foo_bar_error_entries)); + return (GQuark) quark; +} +]| +With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and +other peers will see the D-Bus error name org.project.Foo.Bar.Error.AnotherError. + +If the other peer is using GDBus, and has registered the association with +g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark +generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead +of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover +org.project.Foo.Bar.Error.AnotherError using g_dbus_error_get_remote_error(). + +Note that the %G_DBUS_ERROR error domain is intended only +for returning errors from a remote message bus process. Errors +generated locally in-process by e.g. #GDBusConnection should use the +%G_IO_ERROR domain.</doc> + </docsection> + <docsection name="gdbusintrospection"> + <doc xml:space="preserve">Various data structures and convenience routines to parse and +generate D-Bus introspection XML. Introspection information is +used when registering objects with g_dbus_connection_register_object(). + +The format of D-Bus introspection XML is specified in the +[D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format)</doc> + </docsection> + <docsection name="gdbusnameowning"> + <doc xml:space="preserve">Convenience API for owning bus names. + +A simple example for owning a name can be found in +[gdbus-example-own-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-own-name.c)</doc> + </docsection> + <docsection name="gdbusnamewatching"> + <doc xml:space="preserve">Convenience API for watching bus names. + +A simple example for watching a name can be found in +[gdbus-example-watch-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-name.c)</doc> + </docsection> + <docsection name="gdbusutils"> + <doc xml:space="preserve">Various utility routines related to D-Bus.</doc> + </docsection> + <docsection name="gfileattribute"> + <doc xml:space="preserve">File attributes in GIO consist of a list of key-value pairs. + +Keys are strings that contain a key namespace and a key name, separated +by a colon, e.g. "namespace::keyname". Namespaces are included to sort +key-value pairs by namespaces for relevance. Keys can be retrieved +using wildcards, e.g. "standard::*" will return all of the keys in the +"standard" namespace. + +The list of possible attributes for a filesystem (pointed to by a #GFile) is +available as a #GFileAttributeInfoList. This list is queryable by key names +as indicated earlier. + +Information is stored within the list in #GFileAttributeInfo structures. +The info structure can store different types, listed in the enum +#GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will +be set to %G_FILE_ATTRIBUTE_TYPE_INVALID. + +Classes that implement #GFileIface will create a #GFileAttributeInfoList and +install default keys and values for their given file system, architecture, +and other possible implementation details (e.g., on a UNIX system, a file +attribute key will be registered for the user id for a given file). + +## Default Namespaces + +- `"standard"`: The "Standard" namespace. General file information that + any application may need should be put in this namespace. Examples + include the file's name, type, and size. +- `"etag`: The [Entity Tag][gfile-etag] namespace. Currently, the only key + in this namespace is "value", which contains the value of the current + entity tag. +- `"id"`: The "Identification" namespace. This namespace is used by file + managers and applications that list directories to check for loops and + to uniquely identify files. +- `"access"`: The "Access" namespace. Used to check if a user has the + proper privileges to access files and perform file operations. Keys in + this namespace are made to be generic and easily understood, e.g. the + "can_read" key is %TRUE if the current user has permission to read the + file. UNIX permissions and NTFS ACLs in Windows should be mapped to + these values. +- `"mountable"`: The "Mountable" namespace. Includes simple boolean keys + for checking if a file or path supports mount operations, e.g. mount, + unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE. +- `"time"`: The "Time" namespace. Includes file access, changed, created + times. +- `"unix"`: The "Unix" namespace. Includes UNIX-specific information and + may not be available for all files. Examples include the UNIX "UID", + "GID", etc. +- `"dos"`: The "DOS" namespace. Includes DOS-specific information and may + not be available for all files. Examples include "is_system" for checking + if a file is marked as a system file, and "is_archive" for checking if a + file is marked as an archive file. +- `"owner"`: The "Owner" namespace. Includes information about who owns a + file. May not be available for all file systems. Examples include "user" + for getting the user name of the file owner. This information is often + mapped from some backend specific data such as a UNIX UID. +- `"thumbnail"`: The "Thumbnail" namespace. Includes information about file + thumbnails and their location within the file system. Examples of keys in + this namespace include "path" to get the location of a thumbnail, "failed" + to check if thumbnailing of the file failed, and "is-valid" to check if + the thumbnail is outdated. +- `"filesystem"`: The "Filesystem" namespace. Gets information about the + file system where a file is located, such as its type, how much space is + left available, and the overall size of the file system. +- `"gvfs"`: The "GVFS" namespace. Keys in this namespace contain information + about the current GVFS backend in use. +- `"xattr"`: The "xattr" namespace. Gets information about extended + user attributes. See attr(5). The "user." prefix of the extended user + attribute name is stripped away when constructing keys in this namespace, + e.g. "xattr::mime_type" for the extended attribute with the name + "user.mime_type". Note that this information is only available if + GLib has been built with extended attribute support. +- `"xattr-sys"`: The "xattr-sys" namespace. Gets information about + extended attributes which are not user-specific. See attr(5). Note + that this information is only available if GLib has been built with + extended attribute support. +- `"selinux"`: The "SELinux" namespace. Includes information about the + SELinux context of files. Note that this information is only available + if GLib has been built with SELinux support. + +Please note that these are not all of the possible namespaces. +More namespaces can be added from GIO modules or by individual applications. +For more information about writing GIO modules, see #GIOModule. + +<!-- TODO: Implementation note about using extended attributes on supported +file systems --> + +## Default Keys + +For a list of the built-in keys and their types, see the +[GFileInfo][GFileInfo] documentation. + +Note that there are no predefined keys in the "xattr" and "xattr-sys" +namespaces. Keys for the "xattr" namespace are constructed by stripping +away the "user." prefix from the extended user attribute, and prepending +"xattr::". Keys for the "xattr-sys" namespace are constructed by +concatenating "xattr-sys::" with the extended attribute name. All extended +attribute values are returned as hex-encoded strings in which bytes outside +the ASCII range are encoded as escape sequences of the form \x`nn` +where `nn` is a 2-digit hexadecimal number.</doc> + </docsection> + <docsection name="gioerror"> + <doc xml:space="preserve">Contains helper functions for reporting errors to the user.</doc> + </docsection> + <docsection name="gioscheduler"> + <doc xml:space="preserve">As of GLib 2.36, #GIOScheduler is deprecated in favor of +#GThreadPool and #GTask. + +Schedules asynchronous I/O operations. #GIOScheduler integrates +into the main event loop (#GMainLoop) and uses threads.</doc> + </docsection> + <docsection name="gmenuexporter"> + <doc xml:space="preserve">These functions support exporting a #GMenuModel on D-Bus. +The D-Bus interface that is used is a private implementation +detail. + +To access an exported #GMenuModel remotely, use +g_dbus_menu_model_get() to obtain a #GDBusMenuModel.</doc> + </docsection> + <docsection name="gnetworking"> + <doc xml:space="preserve">The `<gio/gnetworking.h>` header can be included to get +various low-level networking-related system headers, automatically +taking care of certain portability issues for you. + +This can be used, for example, if you want to call setsockopt() +on a #GSocket. + +Note that while WinSock has many of the same APIs as the +traditional UNIX socket API, most of them behave at least slightly +differently (particularly with respect to error handling). If you +want your code to work under both UNIX and Windows, you will need +to take these differences into account. + +Also, under GNU libc, certain non-portable functions are only visible +in the headers if you define %_GNU_SOURCE before including them. Note +that this symbol must be defined before including any headers, or it +may not take effect.</doc> + </docsection> + <docsection name="gpollableutils"> + <doc xml:space="preserve">Utility functions for #GPollableInputStream and +#GPollableOutputStream implementations.</doc> + </docsection> + <docsection name="gtls"> + <doc xml:space="preserve">#GTlsConnection and related classes provide TLS (Transport Layer +Security, previously known as SSL, Secure Sockets Layer) support for +gio-based network streams. + +#GDtlsConnection and related classes provide DTLS (Datagram TLS) support for +GIO-based network sockets, using the #GDatagramBased interface. The TLS and +DTLS APIs are almost identical, except TLS is stream-based and DTLS is +datagram-based. They share certificate and backend infrastructure. + +In the simplest case, for a client TLS connection, you can just set the +#GSocketClient:tls flag on a #GSocketClient, and then any +connections created by that client will have TLS negotiated +automatically, using appropriate default settings, and rejecting +any invalid or self-signed certificates (unless you change that +default by setting the #GSocketClient:tls-validation-flags +property). The returned object will be a #GTcpWrapperConnection, +which wraps the underlying #GTlsClientConnection. + +For greater control, you can create your own #GTlsClientConnection, +wrapping a #GSocketConnection (or an arbitrary #GIOStream with +pollable input and output streams) and then connect to its signals, +such as #GTlsConnection::accept-certificate, before starting the +handshake. + +Server-side TLS is similar, using #GTlsServerConnection. At the +moment, there is no support for automatically wrapping server-side +connections in the way #GSocketClient does for client-side +connections.</doc> + </docsection> + <docsection name="gunixmounts"> + <doc xml:space="preserve">Routines for managing mounted UNIX mount points and paths. + +Note that `<gio/gunixmounts.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.</doc> + </docsection> + <docsection name="gwin32inputstream"> + <doc xml:space="preserve">#GWin32InputStream implements #GInputStream for reading from a +Windows file handle. + +Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO +interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file +when using it.</doc> + </docsection> + <docsection name="gwin32outputstream"> + <doc xml:space="preserve">#GWin32OutputStream implements #GOutputStream for writing to a +Windows file handle. + +Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO +interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file +when using it.</doc> + </docsection> + <docsection name="gwin32registrykey"> + <doc xml:space="preserve">#GWin32RegistryKey represents a single Windows Registry key. + +#GWin32RegistryKey is used by a number of helper functions that read +Windows Registry. All keys are opened with read-only access, and at +the moment there is no API for writing into registry keys or creating +new ones. + +#GWin32RegistryKey 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_win32_registry_key_new() and g_win32_registry_key_get_child(), so these +functions can return %NULL. + +To increase efficiency, a UTF-16 variant is available for all functions +that deal with key or value names in the registry. Use these to perform +deep registry queries or other operations that require querying a name +of a key or a value and then opening it (or querying its data). The use +of UTF-16 functions avoids the overhead of converting names to UTF-8 and +back. + +All functions operate in current user's context (it is not possible to +access registry tree of a different user). + +Key paths must use '\\' as a separator, '/' is not supported. Key names +must not include '\\', because it's used as a separator. Value names +can include '\\'. + +Key and value names are not case sensitive. + +Full key name (excluding the pre-defined ancestor's name) can't exceed +255 UTF-16 characters, give or take. Value name can't exceed 16383 UTF-16 +characters. Tree depth is limited to 512 levels.</doc> + </docsection> + <docsection name="gzcompressor"> + <doc xml:space="preserve">#GZlibCompressor is an implementation of #GConverter that +compresses data using zlib.</doc> + </docsection> + <docsection name="gzdecompressor"> + <doc xml:space="preserve">#GZlibDecompressor is an implementation of #GConverter that +decompresses data compressed with zlib.</doc> + </docsection> + <function name="icon_deserialize" c:identifier="g_icon_deserialize" moved-to="Icon.deserialize" version="2.38"> + <doc xml:space="preserve">Deserializes a #GIcon previously serialized using g_icon_serialize().</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GIcon, or %NULL when deserialization fails.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve">a #GVariant created with g_icon_serialize()</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <function name="icon_hash" c:identifier="g_icon_hash" moved-to="Icon.hash"> + <doc xml:space="preserve">Gets a hash for an icon.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #guint containing a hash for the @icon, suitable for +use in a #GHashTable or similar data structure.</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="icon" transfer-ownership="none"> + <doc xml:space="preserve">#gconstpointer to an icon object.</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="icon_new_for_string" c:identifier="g_icon_new_for_string" moved-to="Icon.new_for_string" version="2.20" throws="1"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">An object implementing the #GIcon + interface or %NULL if @error is set.</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve">A string obtained via g_icon_to_string().</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="initable_newv" c:identifier="g_initable_newv" moved-to="Initable.newv" version="2.22" deprecated="1" deprecated-version="2.54" throws="1"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_object_new_with_properties() and +g_initable_init() instead. See #GParameter for more information.</doc-deprecated> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly allocated + #GObject, or %NULL on error</doc> + <type name="GObject.Object" c:type="gpointer"/> + </return-value> + <parameters> + <parameter name="object_type" transfer-ownership="none"> + <doc xml:space="preserve">a #GType supporting #GInitable.</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="n_parameters" transfer-ownership="none"> + <doc xml:space="preserve">the number of parameters in @parameters</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="parameters" transfer-ownership="none"> + <doc xml:space="preserve">the parameters to use to construct the object</doc> + <array length="1" zero-terminated="0" c:type="GParameter*"> + <type name="GObject.Parameter" c:type="GParameter"/> + </array> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="io_error_from_errno" c:identifier="g_io_error_from_errno"> + <doc xml:space="preserve">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</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">#GIOErrorEnum value for the given errno.h error number.</doc> + <type name="IOErrorEnum" c:type="GIOErrorEnum"/> + </return-value> + <parameters> + <parameter name="err_no" transfer-ownership="none"> + <doc xml:space="preserve">Error number as defined in errno.h.</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="io_error_quark" c:identifier="g_io_error_quark"> + <doc xml:space="preserve">Gets the GIO Error Quark.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="io_extension_point_implement" c:identifier="g_io_extension_point_implement" moved-to="IOExtensionPoint.implement"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GIOExtension object for #GType</doc> + <type name="IOExtension" c:type="GIOExtension*"/> + </return-value> + <parameters> + <parameter name="extension_point_name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the extension point</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="type" transfer-ownership="none"> + <doc xml:space="preserve">the #GType to register as extension</doc> + <type name="GType" c:type="GType"/> + </parameter> + <parameter name="extension_name" transfer-ownership="none"> + <doc xml:space="preserve">the name for the extension</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="priority" transfer-ownership="none"> + <doc xml:space="preserve">the priority for the extension</doc> + <type name="gint" c:type="gint"/> + </parameter> + </parameters> + </function> + <function name="io_extension_point_lookup" c:identifier="g_io_extension_point_lookup" moved-to="IOExtensionPoint.lookup"> + <doc xml:space="preserve">Looks up an existing extension point.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the #GIOExtensionPoint, or %NULL if there + is no registered extension point with the given name.</doc> + <type name="IOExtensionPoint" c:type="GIOExtensionPoint*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">the name of the extension point</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="io_extension_point_register" c:identifier="g_io_extension_point_register" moved-to="IOExtensionPoint.register"> + <doc xml:space="preserve">Registers an extension point.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the new #GIOExtensionPoint. This object is + owned by GIO and should not be freed.</doc> + <type name="IOExtensionPoint" c:type="GIOExtensionPoint*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve">The name of the extension point</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="io_modules_load_all_in_directory" c:identifier="g_io_modules_load_all_in_directory"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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().</doc> + <type name="GLib.List" c:type="GList*"> + <type name="IOModule"/> + </type> + </return-value> + <parameters> + <parameter name="dirname" transfer-ownership="none"> + <doc xml:space="preserve">pathname for a directory containing modules + to load.</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="io_modules_load_all_in_directory_with_scope" c:identifier="g_io_modules_load_all_in_directory_with_scope" version="2.30"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">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().</doc> + <type name="GLib.List" c:type="GList*"> + <type name="IOModule"/> + </type> + </return-value> + <parameters> + <parameter name="dirname" transfer-ownership="none"> + <doc xml:space="preserve">pathname for a directory containing modules + to load.</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="scope" transfer-ownership="none"> + <doc xml:space="preserve">a scope to use when scanning the modules.</doc> + <type name="IOModuleScope" c:type="GIOModuleScope*"/> + </parameter> + </parameters> + </function> + <function name="io_modules_scan_all_in_directory" c:identifier="g_io_modules_scan_all_in_directory" version="2.24"> + <doc xml:space="preserve">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 implements 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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="dirname" transfer-ownership="none"> + <doc xml:space="preserve">pathname for a directory containing modules + to scan.</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="io_modules_scan_all_in_directory_with_scope" c:identifier="g_io_modules_scan_all_in_directory_with_scope" version="2.30"> + <doc xml:space="preserve">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 implements 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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="dirname" transfer-ownership="none"> + <doc xml:space="preserve">pathname for a directory containing modules + to scan.</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + <parameter name="scope" transfer-ownership="none"> + <doc xml:space="preserve">a scope to use when scanning the modules</doc> + <type name="IOModuleScope" c:type="GIOModuleScope*"/> + </parameter> + </parameters> + </function> + <function name="io_scheduler_cancel_all_jobs" c:identifier="g_io_scheduler_cancel_all_jobs" deprecated="1"> + <doc xml:space="preserve">Cancels all cancellable I/O jobs. + +A job is cancellable if a #GCancellable was passed into +g_io_scheduler_push_job().</doc> + <doc-deprecated xml:space="preserve">You should never call this function, since you don't +know how other libraries in your program might be making use of +gioscheduler.</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </function> + <function name="io_scheduler_push_job" c:identifier="g_io_scheduler_push_job" deprecated="1"> + <doc xml:space="preserve">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().</doc> + <doc-deprecated xml:space="preserve">use #GThreadPool or g_task_run_in_thread()</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="job_func" transfer-ownership="none" scope="notified" closure="1" destroy="2"> + <doc xml:space="preserve">a #GIOSchedulerJobFunc.</doc> + <type name="IOSchedulerJobFunc" c:type="GIOSchedulerJobFunc"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">data to pass to @job_func</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async"> + <doc xml:space="preserve">a #GDestroyNotify for @user_data, or %NULL</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve">the [I/O priority][io-priority] +of the request.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="keyfile_settings_backend_new" c:identifier="g_keyfile_settings_backend_new"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a keyfile-backed #GSettingsBackend</doc> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">the filename of the keyfile</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="root_path" transfer-ownership="none"> + <doc xml:space="preserve">the path under which all settings keys appear</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="root_group" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the group name corresponding to + @root_path, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="memory_monitor_dup_default" c:identifier="g_memory_monitor_dup_default" moved-to="MemoryMonitor.dup_default" version="2.64"> + <doc xml:space="preserve">Gets a reference to the default #GMemoryMonitor for the system.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new reference to the default #GMemoryMonitor</doc> + <type name="MemoryMonitor" c:type="GMemoryMonitor*"/> + </return-value> + </function> + <function name="memory_settings_backend_new" c:identifier="g_memory_settings_backend_new" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created #GSettingsBackend</doc> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </return-value> + </function> + <function name="network_monitor_get_default" c:identifier="g_network_monitor_get_default" moved-to="NetworkMonitor.get_default" version="2.32"> + <doc xml:space="preserve">Gets the default #GNetworkMonitor for the system.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GNetworkMonitor, which will be + a dummy object if no network monitor is available</doc> + <type name="NetworkMonitor" c:type="GNetworkMonitor*"/> + </return-value> + </function> + <function name="networking_init" c:identifier="g_networking_init" version="2.36"> + <doc xml:space="preserve">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).</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </function> + <function name="null_settings_backend_new" c:identifier="g_null_settings_backend_new" version="2.28"> + <doc xml:space="preserve">Creates a readonly #GSettingsBackend. + +This backend does not allow changes to settings, so all settings +will always have their default values.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a newly created #GSettingsBackend</doc> + <type name="SettingsBackend" c:type="GSettingsBackend*"/> + </return-value> + </function> + <function name="pollable_source_new" c:identifier="g_pollable_source_new" version="2.28"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new #GSource.</doc> + <type name="GLib.Source" c:type="GSource*"/> + </return-value> + <parameters> + <parameter name="pollable_stream" transfer-ownership="none"> + <doc xml:space="preserve">the stream associated with the new source</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + </parameters> + </function> + <function name="pollable_source_new_full" c:identifier="g_pollable_source_new_full" version="2.34"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new #GSource.</doc> + <type name="GLib.Source" c:type="GSource*"/> + </return-value> + <parameters> + <parameter name="pollable_stream" transfer-ownership="none"> + <doc xml:space="preserve">the stream associated with the + new source</doc> + <type name="GObject.Object" c:type="gpointer"/> + </parameter> + <parameter name="child_source" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional child source to attach</doc> + <type name="GLib.Source" c:type="GSource*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable to attach</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="pollable_stream_read" c:identifier="g_pollable_stream_read" version="2.34" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes read, or -1 on error.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GInputStream</doc> + <type name="InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">a buffer to + read data into</doc> + <array length="2" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to read</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="blocking" transfer-ownership="none"> + <doc xml:space="preserve">whether to do blocking I/O</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="pollable_stream_write" c:identifier="g_pollable_stream_write" version="2.34" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes written, or -1 on error.</doc> + <type name="gssize" c:type="gssize"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">the buffer + containing the data to write.</doc> + <array length="2" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="blocking" transfer-ownership="none"> + <doc xml:space="preserve">whether to do blocking I/O</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="pollable_stream_write_all" c:identifier="g_pollable_stream_write_all" version="2.34" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE on success, %FALSE if there was an error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <doc xml:space="preserve">a #GOutputStream.</doc> + <type name="OutputStream" c:type="GOutputStream*"/> + </parameter> + <parameter name="buffer" transfer-ownership="none"> + <doc xml:space="preserve">the buffer + containing the data to write.</doc> + <array length="2" zero-terminated="0" c:type="void*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="count" transfer-ownership="none"> + <doc xml:space="preserve">the number of bytes to write</doc> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="blocking" transfer-ownership="none"> + <doc xml:space="preserve">whether to do blocking I/O</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full"> + <doc xml:space="preserve">location to store the number of bytes that was + written to the stream</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">optional #GCancellable object, %NULL to ignore.</doc> + <type name="Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="proxy_get_default_for_protocol" c:identifier="g_proxy_get_default_for_protocol" moved-to="Proxy.get_default_for_protocol" version="2.26"> + <doc xml:space="preserve">Find the `gio-proxy` extension point for a proxy implementation that supports +the specified protocol.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">return a #GProxy or NULL if protocol + is not supported.</doc> + <type name="Proxy" c:type="GProxy*"/> + </return-value> + <parameters> + <parameter name="protocol" transfer-ownership="none"> + <doc xml:space="preserve">the proxy protocol name (e.g. http, socks, etc)</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="proxy_resolver_get_default" c:identifier="g_proxy_resolver_get_default" moved-to="ProxyResolver.get_default" version="2.26"> + <doc xml:space="preserve">Gets the default #GProxyResolver for the system.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the default #GProxyResolver, which + will be a dummy object if no proxy resolver is available</doc> + <type name="ProxyResolver" c:type="GProxyResolver*"/> + </return-value> + </function> + <function name="resolver_error_quark" c:identifier="g_resolver_error_quark" moved-to="ResolverError.quark" version="2.22"> + <doc xml:space="preserve">Gets the #GResolver Error Quark.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="resource_error_quark" c:identifier="g_resource_error_quark" moved-to="ResourceError.quark" version="2.32"> + <doc xml:space="preserve">Gets the #GResource Error Quark.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="resource_load" c:identifier="g_resource_load" moved-to="Resource.load" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GResource, or %NULL on error</doc> + <type name="Resource" c:type="GResource*"/> + </return-value> + <parameters> + <parameter name="filename" transfer-ownership="none"> + <doc xml:space="preserve">the path of a filename to load, in the GLib filename encoding</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="resources_enumerate_children" c:identifier="g_resources_enumerate_children" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">an array of constant strings</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">A pathname inside the resource</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="lookup_flags" transfer-ownership="none"> + <doc xml:space="preserve">A #GResourceLookupFlags</doc> + <type name="ResourceLookupFlags" c:type="GResourceLookupFlags"/> + </parameter> + </parameters> + </function> + <function name="resources_get_info" c:identifier="g_resources_get_info" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the file was found. %FALSE if there were errors</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">A pathname inside the resource</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="lookup_flags" transfer-ownership="none"> + <doc xml:space="preserve">A #GResourceLookupFlags</doc> + <type name="ResourceLookupFlags" c:type="GResourceLookupFlags"/> + </parameter> + <parameter name="size" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to place the length of the contents of the file, + or %NULL if the length is not needed</doc> + <type name="gsize" c:type="gsize*"/> + </parameter> + <parameter name="flags" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">a location to place the #GResourceFlags about the file, + or %NULL if the flags are not needed</doc> + <type name="guint32" c:type="guint32*"/> + </parameter> + </parameters> + </function> + <function name="resources_lookup_data" c:identifier="g_resources_lookup_data" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GBytes or %NULL on error. + Free the returned object with g_bytes_unref()</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </return-value> + <parameters> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">A pathname inside the resource</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="lookup_flags" transfer-ownership="none"> + <doc xml:space="preserve">A #GResourceLookupFlags</doc> + <type name="ResourceLookupFlags" c:type="GResourceLookupFlags"/> + </parameter> + </parameters> + </function> + <function name="resources_open_stream" c:identifier="g_resources_open_stream" version="2.32" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">#GInputStream or %NULL on error. + Free the returned object with g_object_unref()</doc> + <type name="InputStream" c:type="GInputStream*"/> + </return-value> + <parameters> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve">A pathname inside the resource</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="lookup_flags" transfer-ownership="none"> + <doc xml:space="preserve">A #GResourceLookupFlags</doc> + <type name="ResourceLookupFlags" c:type="GResourceLookupFlags"/> + </parameter> + </parameters> + </function> + <function name="resources_register" c:identifier="g_resources_register" version="2.32"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="resource" transfer-ownership="none"> + <doc xml:space="preserve">A #GResource</doc> + <type name="Resource" c:type="GResource*"/> + </parameter> + </parameters> + </function> + <function name="resources_unregister" c:identifier="g_resources_unregister" version="2.32"> + <doc xml:space="preserve">Unregisters the resource from the process-global set of resources.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="resource" transfer-ownership="none"> + <doc xml:space="preserve">A #GResource</doc> + <type name="Resource" c:type="GResource*"/> + </parameter> + </parameters> + </function> + <function name="settings_schema_source_get_default" c:identifier="g_settings_schema_source_get_default" moved-to="SettingsSchemaSource.get_default" version="2.32"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">the default schema source</doc> + <type name="SettingsSchemaSource" c:type="GSettingsSchemaSource*"/> + </return-value> + </function> + <function name="simple_async_report_error_in_idle" c:identifier="g_simple_async_report_error_in_idle" introspectable="0" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">Reports an error in an asynchronous function in an idle function by +directly setting the contents of the #GAsyncResult with the given error +information.</doc> + <doc-deprecated xml:space="preserve">Use g_task_report_error().</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GObject, or %NULL.</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="domain" transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark containing the error domain (usually #G_IO_ERROR).</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </parameter> + <parameter name="code" transfer-ownership="none"> + <doc xml:space="preserve">a specific error code.</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="format" transfer-ownership="none"> + <doc xml:space="preserve">a formatted error reporting string.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve">a list of variables to fill in @format.</doc> + <varargs/> + </parameter> + </parameters> + </function> + <function name="simple_async_report_gerror_in_idle" c:identifier="g_simple_async_report_gerror_in_idle" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_task_report_error().</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GObject, or %NULL</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">the #GError to report</doc> + <type name="GLib.Error" c:type="const GError*"/> + </parameter> + </parameters> + </function> + <function name="simple_async_report_take_gerror_in_idle" c:identifier="g_simple_async_report_take_gerror_in_idle" version="2.28" introspectable="0" deprecated="1" deprecated-version="2.46"> + <doc xml:space="preserve">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.</doc> + <doc-deprecated xml:space="preserve">Use g_task_report_error().</doc-deprecated> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="object" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">a #GObject, or %NULL</doc> + <type name="GObject.Object" c:type="GObject*"/> + </parameter> + <parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="2"> + <doc xml:space="preserve">a #GAsyncReadyCallback.</doc> + <type name="AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">user data passed to @callback.</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="error" transfer-ownership="none"> + <doc xml:space="preserve">the #GError to report</doc> + <type name="GLib.Error" c:type="GError*"/> + </parameter> + </parameters> + </function> + <function name="srv_target_list_sort" c:identifier="g_srv_target_list_sort" moved-to="SrvTarget.list_sort" version="2.22" introspectable="0"> + <doc xml:space="preserve">Sorts @targets in place according to the algorithm in RFC 2782.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the head of the sorted list.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </return-value> + <parameters> + <parameter name="targets" transfer-ownership="none"> + <doc xml:space="preserve">a #GList of #GSrvTarget</doc> + <type name="GLib.List" c:type="GList*"> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + </parameters> + </function> + <function name="tls_backend_get_default" c:identifier="g_tls_backend_get_default" moved-to="TlsBackend.get_default" version="2.28"> + <doc xml:space="preserve">Gets the default #GTlsBackend for the system.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GTlsBackend, which will be a + dummy object if no TLS backend is available</doc> + <type name="TlsBackend" c:type="GTlsBackend*"/> + </return-value> + </function> + <function name="tls_channel_binding_error_quark" c:identifier="g_tls_channel_binding_error_quark" moved-to="TlsChannelBindingError.quark" version="2.66"> + <doc xml:space="preserve">Gets the TLS channel binding error quark.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="tls_client_connection_new" c:identifier="g_tls_client_connection_new" moved-to="TlsClientConnection.new" version="2.28" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new +#GTlsClientConnection, or %NULL on error</doc> + <type name="TlsClientConnection" c:type="GIOStream*"/> + </return-value> + <parameters> + <parameter name="base_io_stream" transfer-ownership="none"> + <doc xml:space="preserve">the #GIOStream to wrap</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="server_identity" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the expected identity of the server</doc> + <type name="SocketConnectable" c:type="GSocketConnectable*"/> + </parameter> + </parameters> + </function> + <function name="tls_error_quark" c:identifier="g_tls_error_quark" moved-to="TlsError.quark" version="2.28"> + <doc xml:space="preserve">Gets the TLS error quark.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a #GQuark.</doc> + <type name="GLib.Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="tls_file_database_new" c:identifier="g_tls_file_database_new" moved-to="TlsFileDatabase.new" version="2.30" throws="1"> + <doc xml:space="preserve">Creates a new #GTlsFileDatabase which uses anchor certificate authorities +in @anchors to verify certificate chains. + +The certificates in @anchors must be PEM encoded.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new +#GTlsFileDatabase, or %NULL on error</doc> + <type name="TlsFileDatabase" c:type="GTlsDatabase*"/> + </return-value> + <parameters> + <parameter name="anchors" transfer-ownership="none"> + <doc xml:space="preserve">filename of anchor certificate authorities.</doc> + <type name="filename" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="tls_server_connection_new" c:identifier="g_tls_server_connection_new" moved-to="TlsServerConnection.new" version="2.28" throws="1"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">the new +#GTlsServerConnection, or %NULL on error</doc> + <type name="TlsServerConnection" c:type="GIOStream*"/> + </return-value> + <parameters> + <parameter name="base_io_stream" transfer-ownership="none"> + <doc xml:space="preserve">the #GIOStream to wrap</doc> + <type name="IOStream" c:type="GIOStream*"/> + </parameter> + <parameter name="certificate" transfer-ownership="none" nullable="1" allow-none="1"> + <doc xml:space="preserve">the default server certificate, or %NULL</doc> + <type name="TlsCertificate" c:type="GTlsCertificate*"/> + </parameter> + </parameters> + </function> + <function name="unix_is_mount_path_system_internal" c:identifier="g_unix_is_mount_path_system_internal"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @mount_path is considered an implementation detail + of the OS.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="mount_path" transfer-ownership="none"> + <doc xml:space="preserve">a mount path, e.g. `/media/disk` or `/usr`</doc> + <type name="filename" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="unix_is_system_device_path" c:identifier="g_unix_is_system_device_path" version="2.56"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @device_path is considered an implementation detail of + the OS.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="device_path" transfer-ownership="none"> + <doc xml:space="preserve">a device path, e.g. `/dev/loop0` or `nfsd`</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="unix_is_system_fs_type" c:identifier="g_unix_is_system_fs_type" version="2.56"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @fs_type is considered an implementation detail of the OS.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="fs_type" transfer-ownership="none"> + <doc xml:space="preserve">a file system type, e.g. `procfs` or `tmpfs`</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_at" c:identifier="g_unix_mount_at"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GUnixMountEntry.</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </return-value> + <parameters> + <parameter name="mount_path" transfer-ownership="none"> + <doc xml:space="preserve">path for a possible unix mount.</doc> + <type name="filename" c:type="const char*"/> + </parameter> + <parameter name="time_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">guint64 to contain a timestamp.</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_compare" c:identifier="g_unix_mount_compare"> + <doc xml:space="preserve">Compares two unix mounts.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">1, 0 or -1 if @mount1 is greater than, equal to, +or less than @mount2, respectively.</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <parameter name="mount1" transfer-ownership="none"> + <doc xml:space="preserve">first #GUnixMountEntry to compare.</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </parameter> + <parameter name="mount2" transfer-ownership="none"> + <doc xml:space="preserve">second #GUnixMountEntry to compare.</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_copy" c:identifier="g_unix_mount_copy" version="2.54"> + <doc xml:space="preserve">Makes a copy of @mount_entry.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a new #GUnixMountEntry</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </return-value> + <parameters> + <parameter name="mount_entry" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountEntry.</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_for" c:identifier="g_unix_mount_for" version="2.52"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GUnixMountEntry.</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </return-value> + <parameters> + <parameter name="file_path" transfer-ownership="none"> + <doc xml:space="preserve">file path on some unix mount.</doc> + <type name="filename" c:type="const char*"/> + </parameter> + <parameter name="time_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">guint64 to contain a timestamp.</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_free" c:identifier="g_unix_mount_free"> + <doc xml:space="preserve">Frees a unix mount.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="mount_entry" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountEntry.</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_get_device_path" c:identifier="g_unix_mount_get_device_path"> + <doc xml:space="preserve">Gets the device path for a unix mount.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a string containing the device path.</doc> + <type name="filename" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="mount_entry" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMount.</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_get_fs_type" c:identifier="g_unix_mount_get_fs_type"> + <doc xml:space="preserve">Gets the filesystem type for the unix mount.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">a string containing the file system type.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="mount_entry" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMount.</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_get_mount_path" c:identifier="g_unix_mount_get_mount_path"> + <doc xml:space="preserve">Gets the mount path for a unix mount.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">the mount path for @mount_entry.</doc> + <type name="filename" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="mount_entry" transfer-ownership="none"> + <doc xml:space="preserve">input #GUnixMountEntry to get the mount path for.</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_get_options" c:identifier="g_unix_mount_get_options" version="2.58"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing the options, or %NULL if not +available.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="mount_entry" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountEntry.</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_get_root_path" c:identifier="g_unix_mount_get_root_path" version="2.60"> + <doc xml:space="preserve">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".</doc> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve">a string containing the root, or %NULL if not supported.</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="mount_entry" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountEntry.</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_guess_can_eject" c:identifier="g_unix_mount_guess_can_eject"> + <doc xml:space="preserve">Guesses whether a Unix mount can be ejected.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @mount_entry is deemed to be ejectable.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="mount_entry" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountEntry</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_guess_icon" c:identifier="g_unix_mount_guess_icon"> + <doc xml:space="preserve">Guesses the icon of a Unix mount.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="mount_entry" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountEntry</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_guess_name" c:identifier="g_unix_mount_guess_name"> + <doc xml:space="preserve">Guesses the name of a Unix mount. +The result is a translated string.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">A newly allocated string that must + be freed with g_free()</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="mount_entry" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountEntry</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_guess_should_display" c:identifier="g_unix_mount_guess_should_display"> + <doc xml:space="preserve">Guesses whether a Unix mount should be displayed in the UI.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @mount_entry is deemed to be displayable.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="mount_entry" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountEntry</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_guess_symbolic_icon" c:identifier="g_unix_mount_guess_symbolic_icon" version="2.34"> + <doc xml:space="preserve">Guesses the symbolic icon of a Unix mount.</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve">a #GIcon</doc> + <type name="Icon" c:type="GIcon*"/> + </return-value> + <parameters> + <parameter name="mount_entry" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMountEntry</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_is_readonly" c:identifier="g_unix_mount_is_readonly"> + <doc xml:space="preserve">Checks if a unix mount is mounted read only.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if @mount_entry is read only.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="mount_entry" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMount.</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_is_system_internal" c:identifier="g_unix_mount_is_system_internal"> + <doc xml:space="preserve">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.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the unix mount is for a system path.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="mount_entry" transfer-ownership="none"> + <doc xml:space="preserve">a #GUnixMount.</doc> + <type name="UnixMountEntry" c:type="GUnixMountEntry*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_point_at" c:identifier="g_unix_mount_point_at" moved-to="UnixMountPoint.at" version="2.66"> + <doc xml:space="preserve">Gets a #GUnixMountPoint for a given mount path. If @time_read is set, it +will be filled with a unix timestamp for checking if the mount points have +changed since with g_unix_mount_points_changed_since(). + +If more mount points have the same mount path, the last matching mount point +is returned.</doc> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve">a #GUnixMountPoint, or %NULL if no match +is found.</doc> + <type name="UnixMountPoint" c:type="GUnixMountPoint*"/> + </return-value> + <parameters> + <parameter name="mount_path" transfer-ownership="none"> + <doc xml:space="preserve">path for a possible unix mount point.</doc> + <type name="filename" c:type="const char*"/> + </parameter> + <parameter name="time_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">guint64 to contain a timestamp.</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_points_changed_since" c:identifier="g_unix_mount_points_changed_since"> + <doc xml:space="preserve">Checks if the unix mount points have changed since a given unix time.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mount points have changed since @time.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="time" transfer-ownership="none"> + <doc xml:space="preserve">guint64 to contain a timestamp.</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + </parameters> + </function> + <function name="unix_mount_points_get" c:identifier="g_unix_mount_points_get"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + a #GList of the UNIX mountpoints.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="UnixMountPoint"/> + </type> + </return-value> + <parameters> + <parameter name="time_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">guint64 to contain a timestamp.</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + </parameters> + </function> + <function name="unix_mounts_changed_since" c:identifier="g_unix_mounts_changed_since"> + <doc xml:space="preserve">Checks if the unix mounts have changed since a given unix time.</doc> + <return-value transfer-ownership="none"> + <doc xml:space="preserve">%TRUE if the mounts have changed since @time.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="time" transfer-ownership="none"> + <doc xml:space="preserve">guint64 to contain a timestamp.</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + </parameters> + </function> + <function name="unix_mounts_get" c:identifier="g_unix_mounts_get"> + <doc xml:space="preserve">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().</doc> + <return-value transfer-ownership="full"> + <doc xml:space="preserve"> + a #GList of the UNIX mounts.</doc> + <type name="GLib.List" c:type="GList*"> + <type name="UnixMountEntry"/> + </type> + </return-value> + <parameters> + <parameter name="time_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1"> + <doc xml:space="preserve">guint64 to contain a timestamp, or %NULL</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + </parameters> + </function> + </namespace> +</repository> diff --git a/rust-bindings/gir-files/OSTree-1.0.gir b/rust-bindings/gir-files/OSTree-1.0.gir new file mode 100644 index 0000000000..9799111e80 --- /dev/null +++ b/rust-bindings/gir-files/OSTree-1.0.gir @@ -0,0 +1,21326 @@ +<?xml version="1.0"?> +<!-- This file was automatically generated from C sources - DO NOT EDIT! +To affect the contents of this file, edit the original C definitions, +and/or use gtk-doc annotations. --> +<repository version="1.2" + xmlns="http://www.gtk.org/introspection/core/1.0" + xmlns:c="http://www.gtk.org/introspection/c/1.0" + xmlns:glib="http://www.gtk.org/introspection/glib/1.0"> + <include name="Gio" version="2.0"/> + <package name="ostree-1"/> + <namespace name="OSTree" + version="1.0" + shared-library="libostree-1.so.1" + c:identifier-prefixes="Ostree" + c:symbol-prefixes="ostree"> + <alias name="CollectionRefv" c:type="OstreeCollectionRefv"> + <doc xml:space="preserve" + filename="ostree-ref.h" + line="73">A %NULL-terminated array of #OstreeCollectionRef instances, designed to +be used with g_auto(): + +|[<!-- language="C" --> +g_auto(OstreeCollectionRefv) refs = NULL; +]|</doc> + <source-position filename="ostree-ref.h" line="85"/> + <type name="CollectionRef" c:type="OstreeCollectionRef**"/> + </alias> + <alias name="RepoFinderResultv" c:type="OstreeRepoFinderResultv"> + <doc xml:space="preserve" + filename="ostree-repo-finder.h" + line="169">A %NULL-terminated array of #OstreeRepoFinderResult instances, designed to +be used with g_auto(): + +|[<!-- language="C" --> +g_auto(OstreeRepoFinderResultv) results = NULL; +]|</doc> + <source-position filename="ostree-repo-finder.h" line="181"/> + <type name="RepoFinderResult" c:type="OstreeRepoFinderResult**"/> + </alias> + <function-macro name="ASYNC_PROGRESS" + c:identifier="OSTREE_ASYNC_PROGRESS" + introspectable="0"> + <source-position filename="ostree-async-progress.h" line="27"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ASYNC_PROGRESS_CLASS" + c:identifier="OSTREE_ASYNC_PROGRESS_CLASS" + introspectable="0"> + <source-position filename="ostree-async-progress.h" line="28"/> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="ASYNC_PROGRESS_GET_CLASS" + c:identifier="OSTREE_ASYNC_PROGRESS_GET_CLASS" + introspectable="0"> + <source-position filename="ostree-async-progress.h" line="31"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <class name="AsyncProgress" + c:symbol-prefix="async_progress" + c:type="OstreeAsyncProgress" + parent="GObject.Object" + glib:type-name="OstreeAsyncProgress" + glib:get-type="ostree_async_progress_get_type" + glib:type-struct="AsyncProgressClass"> + <source-position filename="ostree-async-progress.h" line="41"/> + <constructor name="new" c:identifier="ostree_async_progress_new"> + <source-position filename="ostree-async-progress.h" line="47"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="462">A new progress object</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </return-value> + </constructor> + <constructor name="new_and_connect" + c:identifier="ostree_async_progress_new_and_connect"> + <source-position filename="ostree-async-progress.h" line="50"/> + <return-value transfer-ownership="full"> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </return-value> + <parameters> + <parameter name="changed" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <type name="gpointer" c:type="gpointer*"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </constructor> + <virtual-method name="changed"> + <source-position filename="ostree-async-progress.h" line="40"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </instance-parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1" + closure="0"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <method name="copy_state" + c:identifier="ostree_async_progress_copy_state" + version="2019.6"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="425">Atomically copies all the state from @self to @dest, without invoking the +callback. +This is used for proxying progress objects across different #GMainContexts.</doc> + <source-position filename="ostree-async-progress.h" line="94"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="427">An #OstreeAsyncProgress to copy from</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </instance-parameter> + <parameter name="dest" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="428">An #OstreeAsyncProgress to copy to</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </parameter> + </parameters> + </method> + <method name="finish" c:identifier="ostree_async_progress_finish"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="480">Process any pending signals, ensuring the main context is cleared +of sources used by this object. Also ensures that no further +events will be queued.</doc> + <source-position filename="ostree-async-progress.h" line="91"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="482">Self</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get" + c:identifier="ostree_async_progress_get" + version="2017.6" + introspectable="0"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="161">Get the values corresponding to zero or more keys from the +#OstreeAsyncProgress. Each key is specified in @... as the key name, followed +by a #GVariant format string, followed by the necessary arguments for that +format string, just as for g_variant_get(). After those arguments is the +next key name. The varargs list must be %NULL-terminated. + +Each format string must make deep copies of its value, as the values stored +in the #OstreeAsyncProgress may be freed from another thread after this +function returns. + +This operation is thread-safe, and all the keys are queried atomically. + +|[<!-- language="C" --> +guint32 outstanding_fetches; +guint64 bytes_received; +g_autofree gchar *status = NULL; +g_autoptr(GVariant) refs_variant = NULL; + +ostree_async_progress_get (progress, + "outstanding-fetches", "u", &outstanding_fetches, + "bytes-received", "t", &bytes_received, + "status", "s", &status, + "refs", "@a{ss}", &refs_variant, + NULL); +]|</doc> + <source-position filename="ostree-async-progress.h" line="56"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="163">an #OstreeAsyncProgress</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </instance-parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="164">key name, format string, #GVariant return locations, …, followed by %NULL</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="get_status" + c:identifier="ostree_async_progress_get_status" + version="2017.6"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="267">Get the human-readable status string from the #OstreeAsyncProgress. This +operation is thread-safe. The retuned value may be %NULL if no status is +set. + +This is a convenience function to get the well-known `status` key.</doc> + <source-position filename="ostree-async-progress.h" line="53"/> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="277">the current status, or %NULL if none is set</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="269">an #OstreeAsyncProgress</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_uint" c:identifier="ostree_async_progress_get_uint"> + <source-position filename="ostree-async-progress.h" line="60"/> + <return-value transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_uint64" + c:identifier="ostree_async_progress_get_uint64"> + <source-position filename="ostree-async-progress.h" line="63"/> + <return-value transfer-ownership="none"> + <type name="guint64" c:type="guint64"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_variant" + c:identifier="ostree_async_progress_get_variant" + version="2017.6"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="115">Look up a key in the #OstreeAsyncProgress and return the #GVariant associated +with it. The lookup is thread-safe.</doc> + <source-position filename="ostree-async-progress.h" line="66"/> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="123">value for the given @key, or %NULL if + it was not set</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="117">an #OstreeAsyncProgress</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="118">a key to look up</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set" + c:identifier="ostree_async_progress_set" + version="2017.6" + introspectable="0"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="290">Set the values for zero or more keys in the #OstreeAsyncProgress. Each key is +specified in @... as the key name, followed by a #GVariant format string, +followed by the necessary arguments for that format string, just as for +g_variant_new(). After those arguments is the next key name. The varargs list +must be %NULL-terminated. + +g_variant_ref_sink() will be called as appropriate on the #GVariant +parameters, so they may be floating. + +This operation is thread-safe, and all the keys are set atomically. + +|[<!-- language="C" --> +guint32 outstanding_fetches = 15; +guint64 bytes_received = 1000; + +ostree_async_progress_set (progress, + "outstanding-fetches", "u", outstanding_fetches, + "bytes-received", "t", bytes_received, + "status", "s", "Updated status", + "refs", "@a{ss}", g_variant_new_parsed ("@a{ss} {}"), + NULL); +]|</doc> + <source-position filename="ostree-async-progress.h" line="74"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="292">an #OstreeAsyncProgress</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </instance-parameter> + <parameter name="..." transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="293">key name, format string, #GVariant parameters, …, followed by %NULL</doc> + <varargs/> + </parameter> + </parameters> + </method> + <method name="set_status" + c:identifier="ostree_async_progress_set_status" + version="2017.6"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="247">Set the human-readable status string for the #OstreeAsyncProgress. This +operation is thread-safe. %NULL may be passed to clear the status. + +This is a convenience function to set the well-known `status` key.</doc> + <source-position filename="ostree-async-progress.h" line="70"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="249">an #OstreeAsyncProgress</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </instance-parameter> + <parameter name="status" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="250">new status string, or %NULL to clear the status</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_uint" c:identifier="ostree_async_progress_set_uint"> + <source-position filename="ostree-async-progress.h" line="78"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="set_uint64" + c:identifier="ostree_async_progress_set_uint64"> + <source-position filename="ostree-async-progress.h" line="82"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="guint64" c:type="guint64"/> + </parameter> + </parameters> + </method> + <method name="set_variant" + c:identifier="ostree_async_progress_set_variant" + version="2017.6"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="364">Assign a new @value to the given @key, replacing any existing value. The +operation is thread-safe. @value may be a floating reference; +g_variant_ref_sink() will be called on it. + +Any watchers of the #OstreeAsyncProgress will be notified of the change if +@value differs from the existing value for @key.</doc> + <source-position filename="ostree-async-progress.h" line="86"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="366">an #OstreeAsyncProgress</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="367">a key to set</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="368">the value to assign to @key</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <glib:signal name="changed" when="last"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="91">Emitted when @self has been changed.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </glib:signal> + </class> + <record name="AsyncProgressClass" + c:type="OstreeAsyncProgressClass" + glib:is-gtype-struct-for="AsyncProgress"> + <source-position filename="ostree-async-progress.h" line="41"/> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + <field name="changed"> + <callback name="changed"> + <source-position filename="ostree-async-progress.h" line="40"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1" + closure="1"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <function-macro name="BOOTCONFIG_PARSER" + c:identifier="OSTREE_BOOTCONFIG_PARSER" + introspectable="0"> + <source-position filename="ostree-bootconfig-parser.h" line="25"/> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="BOOTLOADER" + c:identifier="OSTREE_BOOTLOADER" + introspectable="0"> + <source-position filename="ostree-bootloader.h" line="26"/> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="BOOTLOADER_GET_IFACE" + c:identifier="OSTREE_BOOTLOADER_GET_IFACE" + introspectable="0"> + <source-position filename="ostree-bootloader.h" line="28"/> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="BOOTLOADER_GRUB2" + c:identifier="OSTREE_BOOTLOADER_GRUB2" + introspectable="0"> + <source-position filename="ostree-bootloader-grub2.h" line="25"/> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="BOOTLOADER_SYSLINUX" + c:identifier="OSTREE_BOOTLOADER_SYSLINUX" + introspectable="0"> + <source-position filename="ostree-bootloader-syslinux.h" line="25"/> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="BOOTLOADER_UBOOT" + c:identifier="OSTREE_BOOTLOADER_UBOOT" + introspectable="0"> + <source-position filename="ostree-bootloader-uboot.h" line="29"/> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="BOOTLOADER_ZIPL" + c:identifier="OSTREE_BOOTLOADER_ZIPL" + introspectable="0"> + <source-position filename="ostree-bootloader-zipl.h" line="25"/> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <constant name="BUILT_FEATURES" + value="libsoup gpgme ex-fsverity libarchive selinux avahi libmount systemd release p2p" + c:type="OSTREE_BUILT_FEATURES" + version="2019.3"> + <doc xml:space="preserve" + filename="ostree-version.h" + line="93">Whitespace separated set of features this libostree was configured with at build time. +Consult the source code in configure.ac (or the CLI `ostree --version`) for examples.</doc> + <source-position filename="ostree-version.h" line="100"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <class name="BootconfigParser" + c:symbol-prefix="bootconfig_parser" + c:type="OstreeBootconfigParser" + parent="GObject.Object" + glib:type-name="OstreeBootconfigParser" + glib:get-type="ostree_bootconfig_parser_get_type"> + <constructor name="new" c:identifier="ostree_bootconfig_parser_new"> + <source-position filename="ostree-bootconfig-parser.h" line="34"/> + <return-value transfer-ownership="full"> + <type name="BootconfigParser" c:type="OstreeBootconfigParser*"/> + </return-value> + </constructor> + <method name="clone" c:identifier="ostree_bootconfig_parser_clone"> + <source-position filename="ostree-bootconfig-parser.h" line="37"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-bootconfig-parser.c" + line="44">Copy of @self</doc> + <type name="BootconfigParser" c:type="OstreeBootconfigParser*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-bootconfig-parser.c" + line="42">Bootconfig to clone</doc> + <type name="BootconfigParser" c:type="OstreeBootconfigParser*"/> + </instance-parameter> + </parameters> + </method> + <method name="get" c:identifier="ostree_bootconfig_parser_get"> + <source-position filename="ostree-bootconfig-parser.h" line="71"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="BootconfigParser" c:type="OstreeBootconfigParser*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_overlay_initrds" + c:identifier="ostree_bootconfig_parser_get_overlay_initrds" + version="2020.7"> + <source-position filename="ostree-bootconfig-parser.h" line="79"/> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve" + filename="ostree-bootconfig-parser.c" + line="176">Array of initrds or %NULL +if none are set.</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-bootconfig-parser.c" + line="174">Parser</doc> + <type name="BootconfigParser" c:type="OstreeBootconfigParser*"/> + </instance-parameter> + </parameters> + </method> + <method name="parse" + c:identifier="ostree_bootconfig_parser_parse" + throws="1"> + <source-position filename="ostree-bootconfig-parser.h" line="40"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="BootconfigParser" c:type="OstreeBootconfigParser*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none"> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="parse_at" + c:identifier="ostree_bootconfig_parser_parse_at" + throws="1"> + <doc xml:space="preserve" + filename="ostree-bootconfig-parser.c" + line="59">Initialize a bootconfig from the given file.</doc> + <source-position filename="ostree-bootconfig-parser.h" line="46"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-bootconfig-parser.c" + line="61">Parser</doc> + <type name="BootconfigParser" c:type="OstreeBootconfigParser*"/> + </instance-parameter> + <parameter name="dfd" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-bootconfig-parser.c" + line="62">Directory fd</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-bootconfig-parser.c" + line="63">File path</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-bootconfig-parser.c" + line="64">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set" c:identifier="ostree_bootconfig_parser_set"> + <source-position filename="ostree-bootconfig-parser.h" line="66"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="BootconfigParser" c:type="OstreeBootconfigParser*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="value" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_overlay_initrds" + c:identifier="ostree_bootconfig_parser_set_overlay_initrds" + version="2020.7"> + <doc xml:space="preserve" + filename="ostree-bootconfig-parser.c" + line="152">These are rendered as additional `initrd` keys in the final bootloader configs. The +base initrd is part of the primary keys.</doc> + <source-position filename="ostree-bootconfig-parser.h" line="75"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-bootconfig-parser.c" + line="154">Parser</doc> + <type name="BootconfigParser" c:type="OstreeBootconfigParser*"/> + </instance-parameter> + <parameter name="initrds" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-bootconfig-parser.c" + line="155">Array of overlay + initrds or %NULL to unset.</doc> + <array c:type="char**"> + <type name="utf8" c:type="char*"/> + </array> + </parameter> + </parameters> + </method> + <method name="write" + c:identifier="ostree_bootconfig_parser_write" + throws="1"> + <source-position filename="ostree-bootconfig-parser.h" line="53"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="BootconfigParser" c:type="OstreeBootconfigParser*"/> + </instance-parameter> + <parameter name="output" transfer-ownership="none"> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_at" + c:identifier="ostree_bootconfig_parser_write_at" + throws="1"> + <source-position filename="ostree-bootconfig-parser.h" line="59"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="BootconfigParser" c:type="OstreeBootconfigParser*"/> + </instance-parameter> + <parameter name="dfd" transfer-ownership="none"> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + </class> + <record name="Bootloader" c:type="OstreeBootloader" disguised="1"> + <source-position filename="ostree-bootloader.h" line="30"/> + </record> + <record name="BootloaderGrub2" + c:type="OstreeBootloaderGrub2" + disguised="1"> + <source-position filename="ostree-bootloader-grub2.h" line="28"/> + </record> + <record name="BootloaderInterface" c:type="OstreeBootloaderInterface"> + <source-position filename="ostree-bootloader.h" line="53"/> + <field name="g_iface" writable="1"> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="query"> + <callback name="query" throws="1"> + <source-position filename="ostree-bootloader.h" line="38"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="bootloader" transfer-ownership="none"> + <type name="Bootloader" c:type="OstreeBootloader*"/> + </parameter> + <parameter name="out_is_active" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="get_name"> + <callback name="get_name"> + <source-position filename="ostree-bootloader.h" line="42"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <type name="Bootloader" c:type="OstreeBootloader*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="write_config" introspectable="0"> + <callback name="write_config" introspectable="0" throws="1"> + <source-position filename="ostree-bootloader.h" line="43"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <type name="Bootloader" c:type="OstreeBootloader*"/> + </parameter> + <parameter name="bootversion" transfer-ownership="none"> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="new_deployments" transfer-ownership="none"> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </parameter> + <parameter name="cancellable" transfer-ownership="none"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="post_bls_sync"> + <callback name="post_bls_sync" throws="1"> + <source-position filename="ostree-bootloader.h" line="48"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <type name="Bootloader" c:type="OstreeBootloader*"/> + </parameter> + <parameter name="bootversion" transfer-ownership="none"> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="is_atomic"> + <callback name="is_atomic"> + <source-position filename="ostree-bootloader.h" line="52"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <type name="Bootloader" c:type="OstreeBootloader*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <record name="BootloaderSyslinux" + c:type="OstreeBootloaderSyslinux" + disguised="1"> + <source-position filename="ostree-bootloader-syslinux.h" line="28"/> + </record> + <record name="BootloaderUboot" + c:type="OstreeBootloaderUboot" + disguised="1"> + <source-position filename="ostree-bootloader-uboot.h" line="32"/> + </record> + <record name="BootloaderZipl" c:type="OstreeBootloaderZipl" disguised="1"> + <source-position filename="ostree-bootloader-zipl.h" line="28"/> + </record> + <function-macro name="CHECKSUM_INPUT_STREAM" + c:identifier="OSTREE_CHECKSUM_INPUT_STREAM" + introspectable="0"> + <source-position filename="ostree-checksum-input-stream.h" line="28"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CHECKSUM_INPUT_STREAM_CLASS" + c:identifier="OSTREE_CHECKSUM_INPUT_STREAM_CLASS" + introspectable="0"> + <source-position filename="ostree-checksum-input-stream.h" line="29"/> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CHECKSUM_INPUT_STREAM_GET_CLASS" + c:identifier="OSTREE_CHECKSUM_INPUT_STREAM_GET_CLASS" + introspectable="0"> + <source-position filename="ostree-checksum-input-stream.h" line="32"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="CHECK_VERSION" + c:identifier="OSTREE_CHECK_VERSION" + version="2017.4" + introspectable="0"> + <doc xml:space="preserve" + filename="ostree-version.h" + line="79">Compile-time version checking. Evaluates to %TRUE if the version +of ostree is equal or greater than the required one.</doc> + <source-position filename="ostree-version.h" line="88"/> + <parameters> + <parameter name="year"> + <doc xml:space="preserve" + filename="ostree-version.h" + line="81">required year version</doc> + </parameter> + <parameter name="release"> + <doc xml:space="preserve" + filename="ostree-version.h" + line="82">required release version</doc> + </parameter> + </parameters> + </function-macro> + <constant name="COMMIT_GVARIANT_STRING" + value="(a{sv}aya(say)sstayay)" + c:type="OSTREE_COMMIT_GVARIANT_STRING"> + <source-position filename="ostree-core.h" line="151"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="COMMIT_META_KEY_ARCHITECTURE" + value="ostree.architecture" + c:type="OSTREE_COMMIT_META_KEY_ARCHITECTURE" + version="2020.4"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="222">GVariant type `s`. Intended to describe the CPU architecture. This is a freeform string, and some distributions +which have existing package managers might want to match that schema. If you +don't have a prior schema, it's recommended to use `uname -m` by default (i.e. the Linux kernel schema). In the future +ostree might include a builtin function to compare architectures.</doc> + <source-position filename="ostree-core.h" line="232"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="COMMIT_META_KEY_COLLECTION_BINDING" + value="ostree.collection-binding" + c:type="OSTREE_COMMIT_META_KEY_COLLECTION_BINDING" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="284">GVariant type `s`. If this is added to a commit, `ostree_repo_pull()` +will enforce that the commit was retrieved from a repository which has +the same collection ID. See `ostree_repo_set_collection_id()`. +This is most useful in concert with `OSTREE_COMMIT_META_KEY_REF_BINDING`, +as it more strongly binds the commit to the repository and branch.</doc> + <source-position filename="ostree-core.h" line="295"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="COMMIT_META_KEY_ENDOFLIFE" + value="ostree.endoflife" + c:type="OSTREE_COMMIT_META_KEY_ENDOFLIFE" + version="2017.7"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="244">GVariant type `s`. This metadata key is used to display vendor's message +when an update stream for a particular branch ends. It usually provides +update instructions for the users.</doc> + <source-position filename="ostree-core.h" line="253"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="COMMIT_META_KEY_ENDOFLIFE_REBASE" + value="ostree.endoflife-rebase" + c:type="OSTREE_COMMIT_META_KEY_ENDOFLIFE_REBASE" + version="2017.7"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="234">GVariant type `s`. Should contain a refspec defining a new target branch; +`ostree admin upgrade` and `OstreeSysrootUpgrader` will automatically initiate +a rebase upon encountering this metadata key.</doc> + <source-position filename="ostree-core.h" line="243"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="COMMIT_META_KEY_REF_BINDING" + value="ostree.ref-binding" + c:type="OSTREE_COMMIT_META_KEY_REF_BINDING" + version="2017.9"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="271">GVariant type `as`; each element is a branch name. If this is added to a +commit, `ostree_repo_pull()` will enforce that the commit was retrieved from +one of the branch names in this array. This prevents "sidegrade" attacks. +The rationale for having this support multiple branch names is that it helps +support a "promotion" model of taking a commit and moving it between development +and production branches.</doc> + <source-position filename="ostree-core.h" line="283"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="COMMIT_META_KEY_SOURCE_TITLE" + value="ostree.source-title" + c:type="OSTREE_COMMIT_META_KEY_SOURCE_TITLE" + version="2017.13"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="254">GVariant type `s`. This should hold a relatively short single line value +containing a human-readable "source" for a commit, intended to be displayed +near the origin ref. This is particularly useful for systems that inject +content into an OSTree commit from elsewhere - for example, generating from +an OCI or qcow2 image. Or if generating from packages, the enabled repository +names and their versions. + +Try to keep this key short (e.g. < 80 characters) and human-readable; if you +desire machine readable data, consider injecting separate metadata keys.</doc> + <source-position filename="ostree-core.h" line="269"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="COMMIT_META_KEY_VERSION" + value="version" + c:type="OSTREE_COMMIT_META_KEY_VERSION" + version="2014.9"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="210">GVariant type `s`. This metadata key is used for version numbers. A freeform +string; the intention is that systems using ostree do not interpret this +semantically as traditional package managers do. + +This is the only ostree-defined metadata key that does not start with `ostree.`.</doc> + <source-position filename="ostree-core.h" line="220"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <bitfield name="ChecksumFlags" + version="2017.13" + c:type="OstreeChecksumFlags"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="467">Flags influencing checksumming logic.</doc> + <source-position filename="ostree-core.h" line="484"/> + <member name="none" value="0" c:identifier="OSTREE_CHECKSUM_FLAGS_NONE"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="469">Default checksumming without tweaks. + (Since: 2017.13.)</doc> + </member> + <member name="ignore_xattrs" + value="1" + c:identifier="OSTREE_CHECKSUM_FLAGS_IGNORE_XATTRS"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="471">Ignore xattrs when checksumming. + (Since: 2017.13.)</doc> + </member> + <member name="canonical_permissions" + value="2" + c:identifier="OSTREE_CHECKSUM_FLAGS_CANONICAL_PERMISSIONS"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="473">Use canonical uid/gid/mode + values, for bare-user-only mode. (Since: 2021.4.)</doc> + </member> + </bitfield> + <class name="ChecksumInputStream" + c:symbol-prefix="checksum_input_stream" + c:type="OstreeChecksumInputStream" + parent="Gio.FilterInputStream" + glib:type-name="OstreeChecksumInputStream" + glib:get-type="ostree_checksum_input_stream_get_type" + glib:type-struct="ChecksumInputStreamClass"> + <source-position filename="ostree-checksum-input-stream.h" line="57"/> + <constructor name="new" c:identifier="ostree_checksum_input_stream_new"> + <source-position filename="ostree-checksum-input-stream.h" line="63"/> + <return-value transfer-ownership="full"> + <type name="ChecksumInputStream" + c:type="OstreeChecksumInputStream*"/> + </return-value> + <parameters> + <parameter name="stream" transfer-ownership="none"> + <type name="Gio.InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="checksum" transfer-ownership="none"> + <type name="GLib.Checksum" c:type="GChecksum*"/> + </parameter> + </parameters> + </constructor> + <property name="checksum" + writable="1" + construct-only="1" + transfer-ownership="none"> + <type name="gpointer" c:type="gpointer"/> + </property> + <field name="parent_instance"> + <type name="Gio.FilterInputStream" c:type="GFilterInputStream"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="ChecksumInputStreamPrivate" + c:type="OstreeChecksumInputStreamPrivate*"/> + </field> + </class> + <record name="ChecksumInputStreamClass" + c:type="OstreeChecksumInputStreamClass" + glib:is-gtype-struct-for="ChecksumInputStream"> + <source-position filename="ostree-checksum-input-stream.h" line="57"/> + <field name="parent_class"> + <type name="Gio.FilterInputStreamClass" + c:type="GFilterInputStreamClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <source-position filename="ostree-checksum-input-stream.h" + line="52"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <source-position filename="ostree-checksum-input-stream.h" + line="53"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <source-position filename="ostree-checksum-input-stream.h" + line="54"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <source-position filename="ostree-checksum-input-stream.h" + line="55"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <source-position filename="ostree-checksum-input-stream.h" + line="56"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="ChecksumInputStreamPrivate" + c:type="OstreeChecksumInputStreamPrivate" + disguised="1"> + <source-position filename="ostree-checksum-input-stream.h" line="36"/> + </record> + <record name="CmdPrivateVTable" c:type="OstreeCmdPrivateVTable"> + <source-position filename="ostree-cmdprivate.h" line="36"/> + <field name="ostree_system_generator"> + <callback name="ostree_system_generator" throws="1"> + <source-position filename="ostree-cmdprivate.h" line="29"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="ostree_cmdline" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="normal_dir" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="early_dir" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="late_dir" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="ostree_generate_grub2_config"> + <callback name="ostree_generate_grub2_config" throws="1"> + <source-position filename="ostree-cmdprivate.h" line="30"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="sysroot" transfer-ownership="none"> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </parameter> + <parameter name="bootversion" transfer-ownership="none"> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="target_fd" transfer-ownership="none"> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="ostree_static_delta_dump"> + <callback name="ostree_static_delta_dump" throws="1"> + <source-position filename="ostree-cmdprivate.h" line="31"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="repo" transfer-ownership="none"> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="delta_id" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="ostree_static_delta_query_exists"> + <callback name="ostree_static_delta_query_exists" throws="1"> + <source-position filename="ostree-cmdprivate.h" line="32"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="repo" transfer-ownership="none"> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="delta_id" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_exists" transfer-ownership="none"> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="ostree_static_delta_delete"> + <callback name="ostree_static_delta_delete" throws="1"> + <source-position filename="ostree-cmdprivate.h" line="33"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="repo" transfer-ownership="none"> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="delta_id" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="ostree_repo_verify_bindings"> + <callback name="ostree_repo_verify_bindings" throws="1"> + <source-position filename="ostree-cmdprivate.h" line="34"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="collection_id" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="ref_name" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="commit" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="ostree_finalize_staged"> + <callback name="ostree_finalize_staged" throws="1"> + <source-position filename="ostree-cmdprivate.h" line="35"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="sysroot" transfer-ownership="none"> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </parameter> + <parameter name="cancellable" transfer-ownership="none"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <record name="CollectionRef" + c:type="OstreeCollectionRef" + version="2018.6" + glib:type-name="OstreeCollectionRef" + glib:get-type="ostree_collection_ref_get_type" + c:symbol-prefix="collection_ref"> + <doc xml:space="preserve" + filename="ostree-ref.h" + line="33">A structure which globally uniquely identifies a ref as the tuple +(@collection_id, @ref_name). For backwards compatibility, @collection_id may be %NULL, +indicating a ref name which is not globally unique.</doc> + <source-position filename="ostree-ref.h" line="49"/> + <field name="collection_id" writable="1"> + <doc xml:space="preserve" + filename="ostree-ref.h" + line="35">collection ID which provided the ref, or %NULL if there + is no associated collection</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="ref_name" writable="1"> + <doc xml:space="preserve" + filename="ostree-ref.h" + line="37">ref name</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <constructor name="new" + c:identifier="ostree_collection_ref_new" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="38">Create a new #OstreeCollectionRef containing (@collection_id, @ref_name). If +@collection_id is %NULL, this is equivalent to a plain ref name string (not a +refspec; no remote name is included), which can be used for non-P2P +operations.</doc> + <source-position filename="ostree-ref.h" line="55"/> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="48">a new #OstreeCollectionRef</doc> + <type name="CollectionRef" c:type="OstreeCollectionRef*"/> + </return-value> + <parameters> + <parameter name="collection_id" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="40">a collection ID, or %NULL for a plain ref</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="ref_name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="41">a ref name</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </constructor> + <method name="dup" + c:identifier="ostree_collection_ref_dup" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="68">Create a copy of the given @ref.</doc> + <source-position filename="ostree-ref.h" line="58"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="74">a newly allocated copy of @ref</doc> + <type name="CollectionRef" c:type="OstreeCollectionRef*"/> + </return-value> + <parameters> + <instance-parameter name="ref" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="70">an #OstreeCollectionRef</doc> + <type name="CollectionRef" c:type="const OstreeCollectionRef*"/> + </instance-parameter> + </parameters> + </method> + <method name="free" + c:identifier="ostree_collection_ref_free" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="85">Free the given @ref.</doc> + <source-position filename="ostree-ref.h" line="60"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="ref" transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="87">an #OstreeCollectionRef</doc> + <type name="CollectionRef" c:type="OstreeCollectionRef*"/> + </instance-parameter> + </parameters> + </method> + <function name="dupv" + c:identifier="ostree_collection_ref_dupv" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="145">Copy an array of #OstreeCollectionRefs, including deep copies of all its +elements. @refs must be %NULL-terminated; it may be empty, but must not be +%NULL.</doc> + <source-position filename="ostree-ref.h" line="69"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="153">a newly allocated copy of @refs</doc> + <array c:type="OstreeCollectionRef**"> + <type name="CollectionRef" c:type="OstreeCollectionRef*"/> + </array> + </return-value> + <parameters> + <parameter name="refs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="147">%NULL-terminated array of #OstreeCollectionRefs</doc> + <array c:type="const OstreeCollectionRef* const*"> + <type name="CollectionRef" c:type="OstreeCollectionRef*"/> + </array> + </parameter> + </parameters> + </function> + <function name="equal" + c:identifier="ostree_collection_ref_equal" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="124">Compare @ref1 and @ref2 and return %TRUE if they have the same collection ID and +ref name, and %FALSE otherwise. Both @ref1 and @ref2 must be non-%NULL.</doc> + <source-position filename="ostree-ref.h" line="65"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="132">%TRUE if @ref1 and @ref2 are equal, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="ref1" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="126">an #OstreeCollectionRef</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="ref2" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="127">another #OstreeCollectionRef</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="freev" + c:identifier="ostree_collection_ref_freev" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="173">Free the given array of @refs, including freeing all its elements. @refs +must be %NULL-terminated; it may be empty, but must not be %NULL.</doc> + <source-position filename="ostree-ref.h" line="71"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="refs" transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="175">an array of #OstreeCollectionRefs</doc> + <array c:type="OstreeCollectionRef**"> + <type name="CollectionRef" c:type="OstreeCollectionRef*"/> + </array> + </parameter> + </parameters> + </function> + <function name="hash" + c:identifier="ostree_collection_ref_hash" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="103">Hash the given @ref. This function is suitable for use with #GHashTable. +@ref must be non-%NULL.</doc> + <source-position filename="ostree-ref.h" line="63"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="110">hash value for @ref</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="ref" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="105">an #OstreeCollectionRef</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + </record> + <record name="CommitSizesEntry" + c:type="OstreeCommitSizesEntry" + version="2020.1" + glib:type-name="OstreeCommitSizesEntry" + glib:get-type="ostree_commit_sizes_entry_get_type" + c:symbol-prefix="commit_sizes_entry"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="552">Structure representing an entry in the "ostree.sizes" commit metadata. Each +entry corresponds to an object in the associated commit.</doc> + <source-position filename="ostree-core.h" line="569"/> + <field name="checksum" writable="1"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="554">object checksum</doc> + <type name="utf8" c:type="gchar*"/> + </field> + <field name="objtype" writable="1"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="555">object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </field> + <field name="unpacked" writable="1"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="556">unpacked object size</doc> + <type name="guint64" c:type="guint64"/> + </field> + <field name="archived" writable="1"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="557">compressed object size</doc> + <type name="guint64" c:type="guint64"/> + </field> + <constructor name="new" + c:identifier="ostree_commit_sizes_entry_new" + version="2020.1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2471">Create a new #OstreeCommitSizesEntry for representing an object in a +commit's "ostree.sizes" metadata.</doc> + <source-position filename="ostree-core.h" line="575"/> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2481">a new #OstreeCommitSizesEntry</doc> + <type name="CommitSizesEntry" c:type="OstreeCommitSizesEntry*"/> + </return-value> + <parameters> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2473">object checksum</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2474">object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="unpacked" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2475">unpacked object size</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="archived" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2476">compressed object size</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + </parameters> + </constructor> + <method name="copy" + c:identifier="ostree_commit_sizes_entry_copy" + version="2020.1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2501">Create a copy of the given @entry.</doc> + <source-position filename="ostree-core.h" line="580"/> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2507">a new copy of @entry</doc> + <type name="CommitSizesEntry" c:type="OstreeCommitSizesEntry*"/> + </return-value> + <parameters> + <instance-parameter name="entry" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2503">an #OstreeCommitSizesEntry</doc> + <type name="CommitSizesEntry" + c:type="const OstreeCommitSizesEntry*"/> + </instance-parameter> + </parameters> + </method> + <method name="free" + c:identifier="ostree_commit_sizes_entry_free" + version="2020.1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2521">Free given @entry.</doc> + <source-position filename="ostree-core.h" line="582"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="entry" transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2523">an #OstreeCommitSizesEntry</doc> + <type name="CommitSizesEntry" c:type="OstreeCommitSizesEntry*"/> + </instance-parameter> + </parameters> + </method> + </record> + <class name="ContentWriter" + c:symbol-prefix="content_writer" + c:type="OstreeContentWriter" + parent="Gio.OutputStream" + glib:type-name="OstreeContentWriter" + glib:get-type="ostree_content_writer_get_type" + glib:type-struct="ContentWriterClass"> + <source-position filename="ostree-content-writer.h" line="27"/> + <method name="finish" + c:identifier="ostree_content_writer_finish" + throws="1"> + <doc xml:space="preserve" + filename="ostree-content-writer.c" + line="122">Complete the object write and return the checksum.</doc> + <source-position filename="ostree-content-writer.h" line="30"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-content-writer.c" + line="129">Checksum, or %NULL on error</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-content-writer.c" + line="124">Writer</doc> + <type name="ContentWriter" c:type="OstreeContentWriter*"/> + </instance-parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-content-writer.c" + line="125">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + </class> + <record name="ContentWriterClass" + c:type="OstreeContentWriterClass" + glib:is-gtype-struct-for="ContentWriter"> + <source-position filename="ostree-content-writer.h" line="27"/> + <field name="parent_class"> + <type name="Gio.OutputStreamClass" c:type="GOutputStreamClass"/> + </field> + </record> + <function-macro name="DEPLOYMENT" + c:identifier="OSTREE_DEPLOYMENT" + introspectable="0"> + <source-position filename="ostree-deployment.h" line="25"/> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <constant name="DIRMETA_GVARIANT_STRING" + value="(uuua(ayay))" + c:type="OSTREE_DIRMETA_GVARIANT_STRING"> + <source-position filename="ostree-core.h" line="111"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <class name="Deployment" + c:symbol-prefix="deployment" + c:type="OstreeDeployment" + parent="GObject.Object" + glib:type-name="OstreeDeployment" + glib:get-type="ostree_deployment_get_type"> + <constructor name="new" c:identifier="ostree_deployment_new"> + <source-position filename="ostree-deployment.h" line="50"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="362">New deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </return-value> + <parameters> + <parameter name="index" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="355">Global index into the bootloader entries</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="osname" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="356">"stateroot" for this deployment</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="csum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="357">OSTree commit that will be deployed</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="deployserial" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="358">Unique counter</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="bootcsum" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="359">Kernel/initrd checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="bootserial" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="360">Unique index</doc> + <type name="gint" c:type="int"/> + </parameter> + </parameters> + </constructor> + <function name="origin_remove_transient_state" + c:identifier="ostree_deployment_origin_remove_transient_state" + version="2018.3"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="181">The intention of an origin file is primarily describe the "inputs" that +resulted in a deployment, and it's commonly used to derive the new state. For +example, a key value (in pure libostree mode) is the "refspec". However, +libostree (or other applications) may want to store "transient" state that +should not be carried across upgrades. + +This function just removes all members of the `libostree-transient` group. +The name of that group is available to all libostree users; best practice +would be to prefix values underneath there with a short identifier for your +software. + +Additionally, this function will remove the `origin/unlocked` and +`origin/override-commit` members; these should be considered transient state +that should have been under an explicit group.</doc> + <source-position filename="ostree-deployment.h" line="89"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="origin" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="183">An origin</doc> + <type name="GLib.KeyFile" c:type="GKeyFile*"/> + </parameter> + </parameters> + </function> + <function name="unlocked_state_to_string" + c:identifier="ostree_deployment_unlocked_state_to_string" + version="2016.4"> + <source-position filename="ostree-deployment.h" line="105"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="414">Description of state</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="state" transfer-ownership="none"> + <type name="DeploymentUnlockedState" + c:type="OstreeDeploymentUnlockedState"/> + </parameter> + </parameters> + </function> + <method name="clone" c:identifier="ostree_deployment_clone"> + <source-position filename="ostree-deployment.h" line="92"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="250">New deep copy of @self</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="248">Deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + </parameters> + </method> + <method name="equal" c:identifier="ostree_deployment_equal"> + <source-position filename="ostree-deployment.h" line="47"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="304">%TRUE if deployments have the same osname, csum, and deployserial</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="ap" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="301">A deployment</doc> + <type name="Deployment" c:type="gconstpointer"/> + </instance-parameter> + <parameter name="bp" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="302">A deployment</doc> + <type name="Deployment" c:type="gconstpointer"/> + </parameter> + </parameters> + </method> + <method name="get_bootconfig" + c:identifier="ostree_deployment_get_bootconfig"> + <source-position filename="ostree-deployment.h" line="70"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="92">Boot configuration</doc> + <type name="BootconfigParser" c:type="OstreeBootconfigParser*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="90">Deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_bootcsum" + c:identifier="ostree_deployment_get_bootcsum"> + <source-position filename="ostree-deployment.h" line="66"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_bootserial" + c:identifier="ostree_deployment_get_bootserial"> + <source-position filename="ostree-deployment.h" line="68"/> + <return-value transfer-ownership="none"> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_csum" c:identifier="ostree_deployment_get_csum"> + <source-position filename="ostree-deployment.h" line="64"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_deployserial" + c:identifier="ostree_deployment_get_deployserial"> + <source-position filename="ostree-deployment.h" line="62"/> + <return-value transfer-ownership="none"> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_index" c:identifier="ostree_deployment_get_index"> + <source-position filename="ostree-deployment.h" line="58"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="116">The global index into the bootloader ordering</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="114">Deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_origin" c:identifier="ostree_deployment_get_origin"> + <source-position filename="ostree-deployment.h" line="72"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="104">Origin</doc> + <type name="GLib.KeyFile" c:type="GKeyFile*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="102">Deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_origin_relpath" + c:identifier="ostree_deployment_get_origin_relpath"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="392">Note this function only returns a *relative* path - if you want to +access, it, you must either use fd-relative api such as openat(), +or concatenate it with the full ostree_sysroot_get_path().</doc> + <source-position filename="ostree-deployment.h" line="95"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="400">Path to deployment root directory, relative to sysroot</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="394">A deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_osname" c:identifier="ostree_deployment_get_osname"> + <source-position filename="ostree-deployment.h" line="60"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_unlocked" + c:identifier="ostree_deployment_get_unlocked" + version="2016.4"> + <source-position filename="ostree-deployment.h" line="108"/> + <return-value transfer-ownership="none"> + <type name="DeploymentUnlockedState" + c:type="OstreeDeploymentUnlockedState"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + </parameters> + </method> + <method name="hash" c:identifier="ostree_deployment_hash"> + <source-position filename="ostree-deployment.h" line="45"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="288">An integer suitable for use in a `GHashTable`</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="v" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="286">Deployment</doc> + <type name="Deployment" c:type="gconstpointer"/> + </instance-parameter> + </parameters> + </method> + <method name="is_pinned" + c:identifier="ostree_deployment_is_pinned" + version="2018.3"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="445">See ostree_sysroot_deployment_set_pinned().</doc> + <source-position filename="ostree-deployment.h" line="77"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="451">`TRUE` if deployment will not be subject to GC</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="447">Deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_staged" + c:identifier="ostree_deployment_is_staged" + version="2018.3"> + <source-position filename="ostree-deployment.h" line="75"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="466">`TRUE` if deployment should be "finalized" at shutdown time</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="464">Deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_bootconfig" + c:identifier="ostree_deployment_set_bootconfig"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="150">Set or clear the bootloader configuration.</doc> + <source-position filename="ostree-deployment.h" line="84"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="152">Deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + <parameter name="bootconfig" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="153">Bootloader configuration object</doc> + <type name="BootconfigParser" c:type="OstreeBootconfigParser*"/> + </parameter> + </parameters> + </method> + <method name="set_bootserial" + c:identifier="ostree_deployment_set_bootserial"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="137">Should never have been made public API; don't use this.</doc> + <source-position filename="ostree-deployment.h" line="82"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="139">Deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + <parameter name="index" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="140">Don't use this</doc> + <type name="gint" c:type="int"/> + </parameter> + </parameters> + </method> + <method name="set_index" c:identifier="ostree_deployment_set_index"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="124">Sets the global index into the bootloader ordering.</doc> + <source-position filename="ostree-deployment.h" line="80"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="126">Deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + <parameter name="index" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="127">Index into bootloader ordering</doc> + <type name="gint" c:type="int"/> + </parameter> + </parameters> + </method> + <method name="set_origin" c:identifier="ostree_deployment_set_origin"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="165">Replace the "origin", which is a description of the source +of the deployment and how to update to the next version.</doc> + <source-position filename="ostree-deployment.h" line="86"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="167">Deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </instance-parameter> + <parameter name="origin" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-deployment.c" + line="168">Set the origin for this deployment</doc> + <type name="GLib.KeyFile" c:type="GKeyFile*"/> + </parameter> + </parameters> + </method> + </class> + <enumeration name="DeploymentUnlockedState" + c:type="OstreeDeploymentUnlockedState"> + <source-position filename="ostree-deployment.h" line="102"/> + <member name="none" + value="0" + c:identifier="OSTREE_DEPLOYMENT_UNLOCKED_NONE"> + </member> + <member name="development" + value="1" + c:identifier="OSTREE_DEPLOYMENT_UNLOCKED_DEVELOPMENT"> + </member> + <member name="hotfix" + value="2" + c:identifier="OSTREE_DEPLOYMENT_UNLOCKED_HOTFIX"> + </member> + <member name="transient" + value="3" + c:identifier="OSTREE_DEPLOYMENT_UNLOCKED_TRANSIENT"> + </member> + </enumeration> + <record name="DiffDirsOptions" c:type="OstreeDiffDirsOptions"> + <doc xml:space="preserve" + filename="ostree-diff.h" + line="73">An extensible options structure controlling diff dirs. Make sure +that owner_uid/gid is set to -1 when not used. This is used by +ostree_diff_dirs_with_options().</doc> + <source-position filename="ostree-diff.h" line="90"/> + <field name="owner_uid" writable="1"> + <type name="gint" c:type="gint"/> + </field> + <field name="owner_gid" writable="1"> + <type name="gint" c:type="gint"/> + </field> + <field name="devino_to_csum_cache" writable="1"> + <type name="RepoDevInoCache" c:type="OstreeRepoDevInoCache*"/> + </field> + <field name="unused_bools" writable="1"> + <array zero-terminated="0" fixed-size="7"> + <type name="gboolean" c:type="gboolean"/> + </array> + </field> + <field name="unused_ints" writable="1"> + <array zero-terminated="0" fixed-size="6"> + <type name="gint" c:type="int"/> + </array> + </field> + <field name="unused_ptrs" writable="1"> + <array zero-terminated="0" fixed-size="7"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <bitfield name="DiffFlags" c:type="OstreeDiffFlags"> + <source-position filename="ostree-diff.h" line="35"/> + <member name="none" value="0" c:identifier="OSTREE_DIFF_FLAGS_NONE"> + </member> + <member name="ignore_xattrs" + value="1" + c:identifier="OSTREE_DIFF_FLAGS_IGNORE_XATTRS"> + </member> + </bitfield> + <record name="DiffItem" + c:type="OstreeDiffItem" + glib:type-name="OstreeDiffItem" + glib:get-type="ostree_diff_item_get_type" + c:symbol-prefix="diff_item"> + <source-position filename="ostree-diff.h" line="53"/> + <field name="refcount" writable="1"> + <type name="gint" c:type="gint"/> + </field> + <field name="src" writable="1"> + <type name="Gio.File" c:type="GFile*"/> + </field> + <field name="target" writable="1"> + <type name="Gio.File" c:type="GFile*"/> + </field> + <field name="src_info" writable="1"> + <type name="Gio.FileInfo" c:type="GFileInfo*"/> + </field> + <field name="target_info" writable="1"> + <type name="Gio.FileInfo" c:type="GFileInfo*"/> + </field> + <field name="src_checksum" writable="1"> + <type name="utf8" c:type="char*"/> + </field> + <field name="target_checksum" writable="1"> + <type name="utf8" c:type="char*"/> + </field> + <method name="ref" c:identifier="ostree_diff_item_ref"> + <source-position filename="ostree-diff.h" line="56"/> + <return-value transfer-ownership="full"> + <type name="DiffItem" c:type="OstreeDiffItem*"/> + </return-value> + <parameters> + <instance-parameter name="diffitem" transfer-ownership="none"> + <type name="DiffItem" c:type="OstreeDiffItem*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="ostree_diff_item_unref"> + <source-position filename="ostree-diff.h" line="58"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="diffitem" transfer-ownership="none"> + <type name="DiffItem" c:type="OstreeDiffItem*"/> + </instance-parameter> + </parameters> + </method> + </record> + <function-macro name="ENCODE_VERSION" + c:identifier="OSTREE_ENCODE_VERSION" + introspectable="0"> + <source-position filename="ostree-version.h" line="65"/> + <parameters> + <parameter name="year"> + </parameter> + <parameter name="release"> + </parameter> + </parameters> + </function-macro> + <constant name="FILEMETA_GVARIANT_STRING" + value="(uuua(ayay))" + c:type="OSTREE_FILEMETA_GVARIANT_STRING"> + <source-position filename="ostree-core.h" line="127"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="GPG_KEY_GVARIANT_STRING" + value="(aa{sv}aa{sv}a{sv})" + c:type="OSTREE_GPG_KEY_GVARIANT_STRING"> + <source-position filename="ostree-repo.h" line="1480"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="GPG_VERIFIER" + c:identifier="OSTREE_GPG_VERIFIER" + introspectable="0"> + <source-position filename="ostree-gpg-verifier.h" line="30"/> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="GPG_VERIFY_RESULT" + c:identifier="OSTREE_GPG_VERIFY_RESULT" + introspectable="0"> + <source-position filename="ostree-gpg-verify-result.h" line="28"/> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <enumeration name="GpgError" + version="2017.10" + c:type="OstreeGpgError" + glib:error-domain="OstreeGpgError"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="155">Errors returned by signature creation and verification operations in OSTree. +These may be returned by any API which creates or verifies signatures.</doc> + <source-position filename="ostree-gpg-verify-result.h" line="178"/> + <member name="no_signature" + value="0" + c:identifier="OSTREE_GPG_ERROR_NO_SIGNATURE"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="157">A signature was expected, but not found.</doc> + </member> + <member name="invalid_signature" + value="1" + c:identifier="OSTREE_GPG_ERROR_INVALID_SIGNATURE"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="158">A signature was malformed.</doc> + </member> + <member name="missing_key" + value="2" + c:identifier="OSTREE_GPG_ERROR_MISSING_KEY"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="159">A signature was found, but was created with a key not in the configured keyrings.</doc> + </member> + <member name="expired_signature" + value="3" + c:identifier="OSTREE_GPG_ERROR_EXPIRED_SIGNATURE"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="160">A signature was expired. Since: 2020.1.</doc> + </member> + <member name="expired_key" + value="4" + c:identifier="OSTREE_GPG_ERROR_EXPIRED_KEY"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="161">A signature was found, but the key used to + sign it has expired. Since: 2020.1.</doc> + </member> + <member name="revoked_key" + value="5" + c:identifier="OSTREE_GPG_ERROR_REVOKED_KEY"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="163">A signature was found, but the key used to + sign it has been revoked. Since: 2020.1.</doc> + </member> + </enumeration> + <enumeration name="GpgSignatureAttr" c:type="OstreeGpgSignatureAttr"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="36">Signature attributes available from an #OstreeGpgVerifyResult. +The attribute's #GVariantType is shown in brackets.</doc> + <source-position filename="ostree-gpg-verify-result.h" line="99"/> + <member name="valid" + value="0" + c:identifier="OSTREE_GPG_SIGNATURE_ATTR_VALID"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="38">[#G_VARIANT_TYPE_BOOLEAN] Is the signature valid?</doc> + </member> + <member name="sig_expired" + value="1" + c:identifier="OSTREE_GPG_SIGNATURE_ATTR_SIG_EXPIRED"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="40">[#G_VARIANT_TYPE_BOOLEAN] Has the signature expired?</doc> + </member> + <member name="key_expired" + value="2" + c:identifier="OSTREE_GPG_SIGNATURE_ATTR_KEY_EXPIRED"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="42">[#G_VARIANT_TYPE_BOOLEAN] Has the signing key expired?</doc> + </member> + <member name="key_revoked" + value="3" + c:identifier="OSTREE_GPG_SIGNATURE_ATTR_KEY_REVOKED"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="44">[#G_VARIANT_TYPE_BOOLEAN] Has the signing key been revoked?</doc> + </member> + <member name="key_missing" + value="4" + c:identifier="OSTREE_GPG_SIGNATURE_ATTR_KEY_MISSING"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="46">[#G_VARIANT_TYPE_BOOLEAN] Is the signing key missing?</doc> + </member> + <member name="fingerprint" + value="5" + c:identifier="OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="48">[#G_VARIANT_TYPE_STRING] Fingerprint of the signing key</doc> + </member> + <member name="timestamp" + value="6" + c:identifier="OSTREE_GPG_SIGNATURE_ATTR_TIMESTAMP"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="50">[#G_VARIANT_TYPE_INT64] Signature creation Unix timestamp</doc> + </member> + <member name="exp_timestamp" + value="7" + c:identifier="OSTREE_GPG_SIGNATURE_ATTR_EXP_TIMESTAMP"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="52">[#G_VARIANT_TYPE_INT64] Signature expiration Unix timestamp (0 if no + expiration)</doc> + </member> + <member name="pubkey_algo_name" + value="8" + c:identifier="OSTREE_GPG_SIGNATURE_ATTR_PUBKEY_ALGO_NAME"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="55">[#G_VARIANT_TYPE_STRING] Name of the public key algorithm used to create + the signature</doc> + </member> + <member name="hash_algo_name" + value="9" + c:identifier="OSTREE_GPG_SIGNATURE_ATTR_HASH_ALGO_NAME"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="58">[#G_VARIANT_TYPE_STRING] Name of the hash algorithm used to create the + signature</doc> + </member> + <member name="user_name" + value="10" + c:identifier="OSTREE_GPG_SIGNATURE_ATTR_USER_NAME"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="61">[#G_VARIANT_TYPE_STRING] The name of the signing key's primary user</doc> + </member> + <member name="user_email" + value="11" + c:identifier="OSTREE_GPG_SIGNATURE_ATTR_USER_EMAIL"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="63">[#G_VARIANT_TYPE_STRING] The email address of the signing key's primary + user</doc> + </member> + <member name="fingerprint_primary" + value="12" + c:identifier="OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT_PRIMARY"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="66">[#G_VARIANT_TYPE_STRING] Fingerprint of the signing key's primary key + (will be the same as OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT if the + the signature is already from the primary key rather than a subkey, + and will be the empty string if the key is missing.)</doc> + </member> + <member name="key_exp_timestamp" + value="13" + c:identifier="OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="71">[#G_VARIANT_TYPE_INT64] Key expiration Unix timestamp (0 if no + expiration or if the key is missing)</doc> + </member> + <member name="key_exp_timestamp_primary" + value="14" + c:identifier="OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP_PRIMARY"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="74">[#G_VARIANT_TYPE_INT64] Key expiration Unix timestamp of the signing key's + primary key (will be the same as OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP + if the signing key is the primary key and 0 if no expiration or if the key + is missing)</doc> + </member> + </enumeration> + <bitfield name="GpgSignatureFormatFlags" + c:type="OstreeGpgSignatureFormatFlags"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="125">Formatting flags for ostree_gpg_verify_result_describe(). Currently +there's only one possible output format, but this enumeration allows +for future variations.</doc> + <source-position filename="ostree-gpg-verify-result.h" line="136"/> + <member name="gpg_signature_format_default" + value="0" + c:identifier="OSTREE_GPG_SIGNATURE_FORMAT_DEFAULT"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.h" + line="127">Use the default output format</doc> + </member> + </bitfield> + <record name="GpgVerifier" c:type="OstreeGpgVerifier" disguised="1"> + <source-position filename="ostree-gpg-verifier.h" line="35"/> + </record> + <class name="GpgVerifyResult" + c:symbol-prefix="gpg_verify_result" + c:type="OstreeGpgVerifyResult" + parent="GObject.Object" + glib:type-name="OstreeGpgVerifyResult" + glib:get-type="ostree_gpg_verify_result_get_type"> + <implements name="Gio.Initable"/> + <function name="describe_variant" + c:identifier="ostree_gpg_verify_result_describe_variant"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="581">Similar to ostree_gpg_verify_result_describe() but takes a #GVariant of +all attributes for a GPG signature instead of an #OstreeGpgVerifyResult +and signature index. + +The @variant <emphasis>MUST</emphasis> have been created by +ostree_gpg_verify_result_get_all().</doc> + <source-position filename="ostree-gpg-verify-result.h" line="146"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="variant" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="583">a #GVariant from ostree_gpg_verify_result_get_all()</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="output_buffer" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="584">a #GString to hold the description</doc> + <type name="GLib.String" c:type="GString*"/> + </parameter> + <parameter name="line_prefix" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="585">optional line prefix string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="586">flags to adjust the description format</doc> + <type name="GpgSignatureFormatFlags" + c:type="OstreeGpgSignatureFormatFlags"/> + </parameter> + </parameters> + </function> + <method name="count_all" + c:identifier="ostree_gpg_verify_result_count_all"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="168">Counts all the signatures in @result.</doc> + <source-position filename="ostree-gpg-verify-result.h" line="105"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="174">signature count</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="170">an #OstreeGpgVerifyResult</doc> + <type name="GpgVerifyResult" c:type="OstreeGpgVerifyResult*"/> + </instance-parameter> + </parameters> + </method> + <method name="count_valid" + c:identifier="ostree_gpg_verify_result_count_valid"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="194">Counts only the valid signatures in @result.</doc> + <source-position filename="ostree-gpg-verify-result.h" line="108"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="200">valid signature count</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="196">an #OstreeGpgVerifyResult</doc> + <type name="GpgVerifyResult" c:type="OstreeGpgVerifyResult*"/> + </instance-parameter> + </parameters> + </method> + <method name="describe" c:identifier="ostree_gpg_verify_result_describe"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="506">Appends a brief, human-readable description of the GPG signature at +@signature_index in @result to the @output_buffer. The description +spans multiple lines. A @line_prefix string, if given, will precede +each line of the description. + +The @flags argument is reserved for future variations to the description +format. Currently must be 0. + +It is a programmer error to request an invalid @signature_index. Use +ostree_gpg_verify_result_count_all() to find the number of signatures in +@result.</doc> + <source-position filename="ostree-gpg-verify-result.h" line="139"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="508">an #OstreeGpgVerifyResult</doc> + <type name="GpgVerifyResult" c:type="OstreeGpgVerifyResult*"/> + </instance-parameter> + <parameter name="signature_index" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="509">which signature to describe</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="output_buffer" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="510">a #GString to hold the description</doc> + <type name="GLib.String" c:type="GString*"/> + </parameter> + <parameter name="line_prefix" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="511">optional line prefix string</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="512">flags to adjust the description format</doc> + <type name="GpgSignatureFormatFlags" + c:type="OstreeGpgSignatureFormatFlags"/> + </parameter> + </parameters> + </method> + <method name="get" c:identifier="ostree_gpg_verify_result_get"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="286">Builds a #GVariant tuple of requested attributes for the GPG signature at +@signature_index in @result. See the #OstreeGpgSignatureAttr description +for the #GVariantType of each available attribute. + +It is a programmer error to request an invalid #OstreeGpgSignatureAttr or +an invalid @signature_index. Use ostree_gpg_verify_result_count_all() to +find the number of signatures in @result.</doc> + <source-position filename="ostree-gpg-verify-result.h" line="116"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="301">a new, floating, #GVariant tuple</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="288">an #OstreeGpgVerifyResult</doc> + <type name="GpgVerifyResult" c:type="OstreeGpgVerifyResult*"/> + </instance-parameter> + <parameter name="signature_index" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="289">which signature to get attributes from</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="attrs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="290">Array of requested attributes</doc> + <array length="2" + zero-terminated="0" + c:type="OstreeGpgSignatureAttr*"> + <type name="GpgSignatureAttr" c:type="OstreeGpgSignatureAttr"/> + </array> + </parameter> + <parameter name="n_attrs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="291">Length of the @attrs array</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="get_all" c:identifier="ostree_gpg_verify_result_get_all"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="464">Builds a #GVariant tuple of all available attributes for the GPG signature +at @signature_index in @result. + +The child values in the returned #GVariant tuple are ordered to match the +#OstreeGpgSignatureAttr enumeration, which means the enum values can be +used as index values in functions like g_variant_get_child(). See the +#OstreeGpgSignatureAttr description for the #GVariantType of each +available attribute. + +<note> + <para> + The #OstreeGpgSignatureAttr enumeration may be extended in the future + with new attributes, which would affect the #GVariant tuple returned by + this function. While the position and type of current child values in + the #GVariant tuple will not change, to avoid backward-compatibility + issues <emphasis>please do not depend on the tuple's overall size or + type signature</emphasis>. + </para> +</note> + +It is a programmer error to request an invalid @signature_index. Use +ostree_gpg_verify_result_count_all() to find the number of signatures in +@result.</doc> + <source-position filename="ostree-gpg-verify-result.h" line="122"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="493">a new, floating, #GVariant tuple</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="466">an #OstreeGpgVerifyResult</doc> + <type name="GpgVerifyResult" c:type="OstreeGpgVerifyResult*"/> + </instance-parameter> + <parameter name="signature_index" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="467">which signature to get attributes from</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </method> + <method name="lookup" c:identifier="ostree_gpg_verify_result_lookup"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="221">Searches @result for a signature signed by @key_id. If a match is found, +the function returns %TRUE and sets @out_signature_index so that further +signature details can be obtained through ostree_gpg_verify_result_get(). +If no match is found, the function returns %FALSE and leaves +@out_signature_index unchanged.</doc> + <source-position filename="ostree-gpg-verify-result.h" line="111"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="234">%TRUE on success, %FALSE on failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="223">an #OstreeGpgVerifyResult</doc> + <type name="GpgVerifyResult" c:type="OstreeGpgVerifyResult*"/> + </instance-parameter> + <parameter name="key_id" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="224">a GPG key ID or fingerprint</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="out_signature_index" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="225">return location for the index of the signature + signed by @key_id, or %NULL</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </method> + <method name="require_valid_signature" + c:identifier="ostree_gpg_verify_result_require_valid_signature" + version="2016.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="746">Checks if the result contains at least one signature from the +trusted keyring. You can call this function immediately after +ostree_repo_verify_summary() or ostree_repo_verify_commit_ext() - +it will handle the %NULL @result and filled @error too.</doc> + <source-position filename="ostree-gpg-verify-result.h" line="152"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="756">%TRUE if @result was not %NULL and had at least one +signature from trusted keyring, otherwise %FALSE</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="result" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="748">an #OstreeGpgVerifyResult</doc> + <type name="GpgVerifyResult" c:type="OstreeGpgVerifyResult*"/> + </instance-parameter> + </parameters> + </method> + </class> + <function-macro name="IS_ASYNC_PROGRESS" + c:identifier="OSTREE_IS_ASYNC_PROGRESS" + introspectable="0"> + <source-position filename="ostree-async-progress.h" line="29"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_ASYNC_PROGRESS_CLASS" + c:identifier="OSTREE_IS_ASYNC_PROGRESS_CLASS" + introspectable="0"> + <source-position filename="ostree-async-progress.h" line="30"/> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_BOOTCONFIG_PARSER" + c:identifier="OSTREE_IS_BOOTCONFIG_PARSER" + introspectable="0"> + <source-position filename="ostree-bootconfig-parser.h" line="26"/> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_BOOTLOADER" + c:identifier="OSTREE_IS_BOOTLOADER" + introspectable="0"> + <source-position filename="ostree-bootloader.h" line="27"/> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_BOOTLOADER_GRUB2" + c:identifier="OSTREE_IS_BOOTLOADER_GRUB2" + introspectable="0"> + <source-position filename="ostree-bootloader-grub2.h" line="26"/> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_BOOTLOADER_SYSLINUX" + c:identifier="OSTREE_IS_BOOTLOADER_SYSLINUX" + introspectable="0"> + <source-position filename="ostree-bootloader-syslinux.h" line="26"/> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_BOOTLOADER_UBOOT" + c:identifier="OSTREE_IS_BOOTLOADER_UBOOT" + introspectable="0"> + <source-position filename="ostree-bootloader-uboot.h" line="30"/> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_BOOTLOADER_ZIPL" + c:identifier="OSTREE_IS_BOOTLOADER_ZIPL" + introspectable="0"> + <source-position filename="ostree-bootloader-zipl.h" line="26"/> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_CHECKSUM_INPUT_STREAM" + c:identifier="OSTREE_IS_CHECKSUM_INPUT_STREAM" + introspectable="0"> + <source-position filename="ostree-checksum-input-stream.h" line="30"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_CHECKSUM_INPUT_STREAM_CLASS" + c:identifier="OSTREE_IS_CHECKSUM_INPUT_STREAM_CLASS" + introspectable="0"> + <source-position filename="ostree-checksum-input-stream.h" line="31"/> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_DEPLOYMENT" + c:identifier="OSTREE_IS_DEPLOYMENT" + introspectable="0"> + <source-position filename="ostree-deployment.h" line="26"/> + <parameters> + <parameter name="inst"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_GPG_VERIFIER" + c:identifier="OSTREE_IS_GPG_VERIFIER" + introspectable="0"> + <source-position filename="ostree-gpg-verifier.h" line="32"/> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_GPG_VERIFY_RESULT" + c:identifier="OSTREE_IS_GPG_VERIFY_RESULT" + introspectable="0"> + <source-position filename="ostree-gpg-verify-result.h" line="30"/> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_LIBARCHIVE_INPUT_STREAM" + c:identifier="OSTREE_IS_LIBARCHIVE_INPUT_STREAM" + introspectable="0"> + <source-position filename="ostree-libarchive-input-stream.h" line="32"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_LIBARCHIVE_INPUT_STREAM_CLASS" + c:identifier="OSTREE_IS_LIBARCHIVE_INPUT_STREAM_CLASS" + introspectable="0"> + <source-position filename="ostree-libarchive-input-stream.h" line="33"/> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_LZMA_COMPRESSOR" + c:identifier="OSTREE_IS_LZMA_COMPRESSOR" + introspectable="0"> + <source-position filename="ostree-lzma-compressor.h" line="29"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_LZMA_COMPRESSOR_CLASS" + c:identifier="OSTREE_IS_LZMA_COMPRESSOR_CLASS" + introspectable="0"> + <source-position filename="ostree-lzma-compressor.h" line="30"/> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_LZMA_DECOMPRESSOR" + c:identifier="OSTREE_IS_LZMA_DECOMPRESSOR" + introspectable="0"> + <source-position filename="ostree-lzma-decompressor.h" line="29"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_LZMA_DECOMPRESSOR_CLASS" + c:identifier="OSTREE_IS_LZMA_DECOMPRESSOR_CLASS" + introspectable="0"> + <source-position filename="ostree-lzma-decompressor.h" line="30"/> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MUTABLE_TREE" + c:identifier="OSTREE_IS_MUTABLE_TREE" + introspectable="0"> + <source-position filename="ostree-mutable-tree.h" line="31"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_MUTABLE_TREE_CLASS" + c:identifier="OSTREE_IS_MUTABLE_TREE_CLASS" + introspectable="0"> + <source-position filename="ostree-mutable-tree.h" line="32"/> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_REPO" + c:identifier="OSTREE_IS_REPO" + introspectable="0"> + <source-position filename="ostree-repo.h" line="40"/> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_REPO_FILE" + c:identifier="OSTREE_IS_REPO_FILE" + introspectable="0"> + <source-position filename="ostree-repo-file.h" line="31"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_REPO_FILE_CLASS" + c:identifier="OSTREE_IS_REPO_FILE_CLASS" + introspectable="0"> + <source-position filename="ostree-repo-file.h" line="32"/> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_REPO_FILE_ENUMERATOR" + c:identifier="OSTREE_IS_REPO_FILE_ENUMERATOR" + introspectable="0"> + <source-position filename="ostree-repo-file-enumerator.h" line="31"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_REPO_FILE_ENUMERATOR_CLASS" + c:identifier="OSTREE_IS_REPO_FILE_ENUMERATOR_CLASS" + introspectable="0"> + <source-position filename="ostree-repo-file-enumerator.h" line="32"/> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SEPOLICY" + c:identifier="OSTREE_IS_SEPOLICY" + introspectable="0"> + <source-position filename="ostree-sepolicy.h" line="29"/> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SYSROOT" + c:identifier="OSTREE_IS_SYSROOT" + introspectable="0"> + <source-position filename="ostree-sysroot.h" line="38"/> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="IS_SYSROOT_UPGRADER" + c:identifier="OSTREE_IS_SYSROOT_UPGRADER" + introspectable="0"> + <source-position filename="ostree-sysroot-upgrader.h" line="29"/> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <record name="KernelArgs" c:type="OstreeKernelArgs" disguised="1"> + <source-position filename="ostree-kernel-args.h" line="27"/> + <method name="append" + c:identifier="ostree_kernel_args_append" + version="2019.3"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="504">Appends @arg which is in the form of key=value pair to the hash table kargs->table +(appends to the value list if key is already in the hash table) +and appends key to kargs->order if it is not in the hash table already.</doc> + <source-position filename="ostree-kernel-args.h" line="84"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="kargs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="506">a OstreeKernelArgs instance</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </instance-parameter> + <parameter name="arg" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="507">key or key/value pair to be added</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="append_argv" + c:identifier="ostree_kernel_args_append_argv" + version="2019.3"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="592">Appends each value in @argv to the corresponding value array and +appends key to kargs->order if it is not in the hash table already.</doc> + <source-position filename="ostree-kernel-args.h" line="88"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="kargs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="594">a OstreeKernelArgs instance</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </instance-parameter> + <parameter name="argv" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="595">an array of key=value argument pairs</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="append_argv_filtered" + c:identifier="ostree_kernel_args_append_argv_filtered" + version="2019.3"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="566">Appends each argument that does not have one of the @prefixes as prefix to the @kargs</doc> + <source-position filename="ostree-kernel-args.h" line="92"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="kargs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="568">a OstreeKernelArgs instance</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </instance-parameter> + <parameter name="argv" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="569">an array of key=value argument pairs</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="prefixes" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="570">an array of prefix strings</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="append_proc_cmdline" + c:identifier="ostree_kernel_args_append_proc_cmdline" + version="2019.3" + throws="1"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="609">Appends the command line arguments in the file "/proc/cmdline" +that does not have "BOOT_IMAGE=" and "initrd=" as prefixes to the @kargs</doc> + <source-position filename="ostree-kernel-args.h" line="112"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="618">%TRUE on success, %FALSE on failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="kargs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="611">a OstreeKernelArgs instance</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </instance-parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="612">optional GCancellable object, NULL to ignore</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="delete" + c:identifier="ostree_kernel_args_delete" + throws="1"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="370">There are few scenarios being handled for deletion: + + 1: for input arg with a single key(i.e without = for split), + the key/value pair will be deleted if there is only + one value that is associated with the key + + 2: for input arg wth key/value pair, the specific key + value pair will be deleted from the pointer array + if those exist. + + 3: If the found key has only one value + associated with it, the key entry in the table will also + be removed, and the key will be removed from order table + + Returns: %TRUE on success, %FALSE on failure + + Since: 2019.3</doc> + <source-position filename="ostree-kernel-args.h" line="102"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="kargs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="372">a OstreeKernelArgs instance</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </instance-parameter> + <parameter name="arg" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="373">key or key/value pair for deletion</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="delete_key_entry" + c:identifier="ostree_kernel_args_delete_key_entry" + version="2019.3" + throws="1"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="330">This function removes the key entry from the hashtable +as well from the order pointer array inside kargs + +Note: since both table and order inside kernel args +are with free function, no extra free functions are +being called as they are done automatically by GLib</doc> + <source-position filename="ostree-kernel-args.h" line="107"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="343">%TRUE on success, %FALSE on failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="kargs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="332">an OstreeKernelArgs instance</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="333">the key to remove</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="free" + c:identifier="ostree_kernel_args_free" + version="2019.3"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="196">Frees the kargs structure</doc> + <source-position filename="ostree-kernel-args.h" line="63"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="kargs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="198">An OstreeKernelArgs that represents kernel arguments</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_last_value" + c:identifier="ostree_kernel_args_get_last_value" + version="2019.3"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="781">Finds and returns the last element of value array +corresponding to the @key in @kargs hash table. Note that the application +will be terminated if the @key is found but the value array is empty</doc> + <source-position filename="ostree-kernel-args.h" line="121"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="790">NULL if @key is not found in the @kargs hash table, +otherwise returns last element of value array corresponding to @key</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="kargs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="783">a OstreeKernelArgs instance</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="784">a key to look for in @kargs hash table</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="new_replace" + c:identifier="ostree_kernel_args_new_replace" + version="2019.3" + throws="1"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="264">This function implements the basic logic behind key/value pair +replacement. Do note that the arg need to be properly formatted + +When replacing key with exact one value, the arg can be in +the form: +key, key=new_val, or key=old_val=new_val +The first one swaps the old_val with the key to an empty value +The second and third replace the old_val into the new_val + +When replacing key with multiple values, the arg can only be +in the form of: +key=old_val=new_val. Unless there is a special case where +there is an empty value associated with the key, then +key=new_val will work because old_val is empty. The empty +val will be swapped with the new_val in that case</doc> + <source-position filename="ostree-kernel-args.h" line="97"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="286">%TRUE on success, %FALSE on failure (and in some other instances such as: +1. key not found in @kargs +2. old value not found when @arg is in the form of key=old_val=new_val +3. multiple old values found when @arg is in the form of key=old_val)</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="kargs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="266">OstreeKernelArgs instance</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </instance-parameter> + <parameter name="arg" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="267">a string argument</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="parse_append" + c:identifier="ostree_kernel_args_parse_append" + version="2019.3"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="653">Parses @options by separating it by whitespaces and appends each argument to @kargs</doc> + <source-position filename="ostree-kernel-args.h" line="117"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="kargs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="655">a OstreeKernelArgs instance</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </instance-parameter> + <parameter name="options" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="656">a string representing command line arguments</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="replace" + c:identifier="ostree_kernel_args_replace" + version="2019.3"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="486">Finds and replaces the old key if @arg is already in the hash table, +otherwise adds @arg as new key and split_keyeq (arg) as value. +Note that when replacing old key value pair, the old values are freed.</doc> + <source-position filename="ostree-kernel-args.h" line="76"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="kargs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="488">a OstreeKernelArgs instance</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </instance-parameter> + <parameter name="arg" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="489">key or key/value pair for replacement</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="replace_argv" + c:identifier="ostree_kernel_args_replace_argv" + version="2019.3"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="542">Finds and replaces each non-null arguments of @argv in the hash table, +otherwise adds individual arg as new key and split_keyeq (arg) as value. +Note that when replacing old key value pair, the old values are freed.</doc> + <source-position filename="ostree-kernel-args.h" line="80"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="kargs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="544">a OstreeKernelArgs instance</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </instance-parameter> + <parameter name="argv" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="545">an array of key or key/value pairs</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="replace_take" + c:identifier="ostree_kernel_args_replace_take" + version="2019.3"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="435">Finds and replaces the old key if @arg is already in the hash table, +otherwise adds @arg as new key and split_keyeq (arg) as value. +Note that when replacing old key, the old values are freed.</doc> + <source-position filename="ostree-kernel-args.h" line="72"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="kargs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="437">a OstreeKernelArgs instance</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </instance-parameter> + <parameter name="arg" transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="438">key or key/value pair for replacement</doc> + <type name="utf8" c:type="char*"/> + </parameter> + </parameters> + </method> + <method name="to_string" + c:identifier="ostree_kernel_args_to_string" + version="2019.3"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="736">Extracts all key value pairs in @kargs and appends to a temporary +GString in forms of "key=value" or "key" if value is NULL separated +by a single whitespace, and returns the temporary string with the +GString wrapper freed + +Note: the application will be terminated if one of the values array +in @kargs is NULL</doc> + <source-position filename="ostree-kernel-args.h" line="131"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="748">a string of "key=value" pairs or "key" if value is NULL, +separated by single whitespaces</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="kargs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="738">a OstreeKernelArgs instance</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </instance-parameter> + </parameters> + </method> + <method name="to_strv" + c:identifier="ostree_kernel_args_to_strv" + version="2019.3"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="703">Extracts all key value pairs in @kargs and appends to a temporary +array in forms of "key=value" or "key" if value is NULL, and returns +the temporary array with the GPtrArray wrapper freed</doc> + <source-position filename="ostree-kernel-args.h" line="128"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="711">an array of "key=value" pairs or "key" if value is NULL</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="kargs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="705">a OstreeKernelArgs instance</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </instance-parameter> + </parameters> + </method> + <function name="cleanup" + c:identifier="ostree_kernel_args_cleanup" + version="2019.3"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="214">Frees the OstreeKernelArgs structure pointed by *loc</doc> + <source-position filename="ostree-kernel-args.h" line="69"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="loc" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="216">Address of an OstreeKernelArgs pointer</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + </parameters> + </function> + <function name="from_string" + c:identifier="ostree_kernel_args_from_string" + version="2019.3" + introspectable="0"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="681">Initializes a new OstreeKernelArgs then parses and appends @options +to the empty OstreeKernelArgs</doc> + <source-position filename="ostree-kernel-args.h" line="125"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="688">newly allocated #OstreeKernelArgs with @options appended</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </return-value> + <parameters> + <parameter name="options" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="683">a string representing command line arguments</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="new" + c:identifier="ostree_kernel_args_new" + version="2019.3" + introspectable="0"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="174">Initializes a new OstreeKernelArgs structure and returns it</doc> + <source-position filename="ostree-kernel-args.h" line="66"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="179">A newly created #OstreeKernelArgs for kernel arguments</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </return-value> + </function> + </record> + <record name="KernelArgsEntry" + c:type="OstreeKernelArgsEntry" + disguised="1"> + <source-position filename="ostree-kernel-args.h" line="28"/> + </record> + <function-macro name="LIBARCHIVE_INPUT_STREAM" + c:identifier="OSTREE_LIBARCHIVE_INPUT_STREAM" + introspectable="0"> + <source-position filename="ostree-libarchive-input-stream.h" line="30"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="LIBARCHIVE_INPUT_STREAM_CLASS" + c:identifier="OSTREE_LIBARCHIVE_INPUT_STREAM_CLASS" + introspectable="0"> + <source-position filename="ostree-libarchive-input-stream.h" line="31"/> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="LIBARCHIVE_INPUT_STREAM_GET_CLASS" + c:identifier="OSTREE_LIBARCHIVE_INPUT_STREAM_GET_CLASS" + introspectable="0"> + <source-position filename="ostree-libarchive-input-stream.h" line="34"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="LZMA_COMPRESSOR" + c:identifier="OSTREE_LZMA_COMPRESSOR" + introspectable="0"> + <source-position filename="ostree-lzma-compressor.h" line="27"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="LZMA_COMPRESSOR_CLASS" + c:identifier="OSTREE_LZMA_COMPRESSOR_CLASS" + introspectable="0"> + <source-position filename="ostree-lzma-compressor.h" line="28"/> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="LZMA_COMPRESSOR_GET_CLASS" + c:identifier="OSTREE_LZMA_COMPRESSOR_GET_CLASS" + introspectable="0"> + <source-position filename="ostree-lzma-compressor.h" line="31"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="LZMA_DECOMPRESSOR" + c:identifier="OSTREE_LZMA_DECOMPRESSOR" + introspectable="0"> + <source-position filename="ostree-lzma-decompressor.h" line="27"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="LZMA_DECOMPRESSOR_CLASS" + c:identifier="OSTREE_LZMA_DECOMPRESSOR_CLASS" + introspectable="0"> + <source-position filename="ostree-lzma-decompressor.h" line="28"/> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="LZMA_DECOMPRESSOR_GET_CLASS" + c:identifier="OSTREE_LZMA_DECOMPRESSOR_GET_CLASS" + introspectable="0"> + <source-position filename="ostree-lzma-decompressor.h" line="31"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <record name="LibarchiveInputStream" c:type="OstreeLibarchiveInputStream"> + <source-position filename="ostree-libarchive-input-stream.h" line="46"/> + <field name="parent_instance" writable="1"> + <type name="Gio.InputStream" c:type="GInputStream"/> + </field> + <field name="priv" readable="0" private="1"> + <type name="LibarchiveInputStreamPrivate" + c:type="OstreeLibarchiveInputStreamPrivate*"/> + </field> + </record> + <record name="LibarchiveInputStreamClass" + c:type="OstreeLibarchiveInputStreamClass"> + <source-position filename="ostree-libarchive-input-stream.h" line="59"/> + <field name="parent_class" writable="1"> + <type name="Gio.InputStreamClass" c:type="GInputStreamClass"/> + </field> + <field name="_g_reserved1" introspectable="0"> + <callback name="_g_reserved1"> + <source-position filename="ostree-libarchive-input-stream.h" + line="54"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved2" introspectable="0"> + <callback name="_g_reserved2"> + <source-position filename="ostree-libarchive-input-stream.h" + line="55"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved3" introspectable="0"> + <callback name="_g_reserved3"> + <source-position filename="ostree-libarchive-input-stream.h" + line="56"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved4" introspectable="0"> + <callback name="_g_reserved4"> + <source-position filename="ostree-libarchive-input-stream.h" + line="57"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + <field name="_g_reserved5" introspectable="0"> + <callback name="_g_reserved5"> + <source-position filename="ostree-libarchive-input-stream.h" + line="58"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + </callback> + </field> + </record> + <record name="LibarchiveInputStreamPrivate" + c:type="OstreeLibarchiveInputStreamPrivate" + disguised="1"> + <source-position filename="ostree-libarchive-input-stream.h" line="38"/> + </record> + <record name="LzmaCompressor" c:type="OstreeLzmaCompressor" disguised="1"> + <doc xml:space="preserve" + filename="ostree-lzma-compressor.c" + line="44">Zlib decompression</doc> + <source-position filename="ostree-lzma-compressor.h" line="34"/> + </record> + <record name="LzmaCompressorClass" c:type="OstreeLzmaCompressorClass"> + <source-position filename="ostree-lzma-compressor.h" line="39"/> + <field name="parent_class" writable="1"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <record name="LzmaDecompressor" + c:type="OstreeLzmaDecompressor" + disguised="1"> + <source-position filename="ostree-lzma-decompressor.h" line="34"/> + </record> + <record name="LzmaDecompressorClass" c:type="OstreeLzmaDecompressorClass"> + <source-position filename="ostree-lzma-decompressor.h" line="39"/> + <field name="parent_class" writable="1"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <constant name="MAX_METADATA_SIZE" + value="10485760" + c:type="OSTREE_MAX_METADATA_SIZE"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="30">Default limit for maximum permitted size in bytes of metadata objects fetched +over HTTP (including repo/config files, refs, and commit/dirtree/dirmeta +objects). This is an arbitrary number intended to mitigate disk space +exhaustion attacks.</doc> + <source-position filename="ostree-core.h" line="38"/> + <type name="gint" c:type="gint"/> + </constant> + <constant name="MAX_METADATA_WARN_SIZE" + value="7340032" + c:type="OSTREE_MAX_METADATA_WARN_SIZE"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="40">This variable is no longer meaningful, it is kept only for compatibility.</doc> + <source-position filename="ostree-core.h" line="45"/> + <type name="gint" c:type="gint"/> + </constant> + <constant name="METADATA_KEY_BOOTABLE" + value="ostree.bootable" + c:type="OSTREE_METADATA_KEY_BOOTABLE" + version="2021.1"> + <doc xml:space="preserve" + filename="ostree-repo-os.h" + line="26">GVariant type `b`: Set if this commit is intended to be bootable</doc> + <source-position filename="ostree-repo-os.h" line="32"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="METADATA_KEY_LINUX" + value="ostree.linux" + c:type="OSTREE_METADATA_KEY_LINUX" + version="2021.1"> + <doc xml:space="preserve" + filename="ostree-repo-os.h" + line="33">GVariant type `s`: Contains the Linux kernel release (i.e. `uname -r`)</doc> + <source-position filename="ostree-repo-os.h" line="39"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="META_KEY_DEPLOY_COLLECTION_ID" + value="ostree.deploy-collection-id" + c:type="OSTREE_META_KEY_DEPLOY_COLLECTION_ID" + version="2018.9"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1661">GVariant type `s`. This key can be used in the repo metadata which is stored +in OSTREE_REPO_METADATA_REF as well as in the summary. The semantics of this +are that the remote repository wants clients to update their remote config +to add this collection ID (clients can't do P2P operations involving a +remote without a collection ID configured on it, even if one is configured +on the server side). Clients must never change or remove a collection ID +already set in their remote config. + +Currently, OSTree does not implement changing a remote config based on this +key, but it may do so in a later release, and until then clients such as +Flatpak may implement it. + +This is a replacement for the similar metadata key implemented by flatpak, +`xa.collection-id`, which is now deprecated as clients which supported it had +bugs with their P2P implementations.</doc> + <source-position filename="ostree-repo.h" line="1682"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="MUTABLE_TREE" + c:identifier="OSTREE_MUTABLE_TREE" + introspectable="0"> + <source-position filename="ostree-mutable-tree.h" line="29"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MUTABLE_TREE_CLASS" + c:identifier="OSTREE_MUTABLE_TREE_CLASS" + introspectable="0"> + <source-position filename="ostree-mutable-tree.h" line="30"/> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="MUTABLE_TREE_GET_CLASS" + c:identifier="OSTREE_MUTABLE_TREE_GET_CLASS" + introspectable="0"> + <source-position filename="ostree-mutable-tree.h" line="33"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <class name="MutableTree" + c:symbol-prefix="mutable_tree" + c:type="OstreeMutableTree" + parent="GObject.Object" + glib:type-name="OstreeMutableTree" + glib:get-type="ostree_mutable_tree_get_type" + glib:type-struct="MutableTreeClass"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="50">Private instance structure.</doc> + <source-position filename="ostree-mutable-tree.h" line="45"/> + <constructor name="new" c:identifier="ostree_mutable_tree_new"> + <source-position filename="ostree-mutable-tree.h" line="51"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="648">A new tree</doc> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </return-value> + </constructor> + <constructor name="new_from_checksum" + c:identifier="ostree_mutable_tree_new_from_checksum" + version="2018.7"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="656">Creates a new OstreeMutableTree with the contents taken from the given repo +and checksums. The data will be loaded from the repo lazily as needed.</doc> + <source-position filename="ostree-mutable-tree.h" line="60"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="665">A new tree</doc> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </return-value> + <parameters> + <parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="658">The repo which contains the objects refered by the checksums.</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="contents_checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="659">dirtree checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="metadata_checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="660">dirmeta checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_commit" + c:identifier="ostree_mutable_tree_new_from_commit" + version="2021.5" + throws="1"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="682">Creates a new OstreeMutableTree with the contents taken from the given commit. +The data will be loaded from the repo lazily as needed.</doc> + <source-position filename="ostree-mutable-tree.h" line="55"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="690">A new tree</doc> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </return-value> + <parameters> + <parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="684">The repo which contains the objects refered by the checksums.</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="rev" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="685">ref or SHA-256 checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </constructor> + <method name="check_error" + c:identifier="ostree_mutable_tree_check_error" + version="2018.7" + throws="1"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="620">In some cases, a tree may be in a "lazy" state that loads +data in the background; if an error occurred during a non-throwing +API call, it will have been cached. This function checks for a +cached error. The tree remains in error state.</doc> + <source-position filename="ostree-mutable-tree.h" line="126"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="630">`TRUE` on success</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="622">Tree</doc> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </instance-parameter> + </parameters> + </method> + <method name="ensure_dir" + c:identifier="ostree_mutable_tree_ensure_dir" + throws="1"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="361">Returns the subdirectory of self with filename @name, creating an empty one +it if it doesn't exist.</doc> + <source-position filename="ostree-mutable-tree.h" line="91"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="363">Tree</doc> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="364">Name of subdirectory of self to retrieve/creates</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_subdir" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="365">the subdirectory</doc> + <type name="MutableTree" c:type="OstreeMutableTree**"/> + </parameter> + </parameters> + </method> + <method name="ensure_parent_dirs" + c:identifier="ostree_mutable_tree_ensure_parent_dirs" + throws="1"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="437">Create all parent trees necessary for the given @split_path to +exist.</doc> + <source-position filename="ostree-mutable-tree.h" line="105"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="439">Tree</doc> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </instance-parameter> + <parameter name="split_path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="440">File path components</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="metadata_checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="441">SHA256 checksum for metadata</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_parent" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="442">The parent tree</doc> + <type name="MutableTree" c:type="OstreeMutableTree**"/> + </parameter> + </parameters> + </method> + <method name="fill_empty_from_dirtree" + c:identifier="ostree_mutable_tree_fill_empty_from_dirtree" + version="2018.7"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="492">Merges @self with the tree given by @contents_checksum and +@metadata_checksum, but only if it's possible without writing new objects to +the @repo. We can do this if either @self is empty, the tree given by +@contents_checksum is empty or if both trees already have the same +@contents_checksum.</doc> + <source-position filename="ostree-mutable-tree.h" line="119"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="501">@TRUE if merge was successful, @FALSE if it was not possible. + +This function enables optimisations when composing trees. The provided +checksums are not loaded or checked when this function is called. Instead +the contents will be loaded only when needed.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </instance-parameter> + <parameter name="repo" transfer-ownership="none"> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="contents_checksum" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="metadata_checksum" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_contents_checksum" + c:identifier="ostree_mutable_tree_get_contents_checksum"> + <source-position filename="ostree-mutable-tree.h" line="76"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_files" c:identifier="ostree_mutable_tree_get_files"> + <source-position filename="ostree-mutable-tree.h" line="132"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="611">All children files (the value is a checksum)</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="utf8"/> + <type name="utf8"/> + </type> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_metadata_checksum" + c:identifier="ostree_mutable_tree_get_metadata_checksum"> + <source-position filename="ostree-mutable-tree.h" line="69"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_subdirs" + c:identifier="ostree_mutable_tree_get_subdirs"> + <source-position filename="ostree-mutable-tree.h" line="130"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="598">All children directories</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="utf8"/> + <type name="MutableTree"/> + </type> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </instance-parameter> + </parameters> + </method> + <method name="lookup" + c:identifier="ostree_mutable_tree_lookup" + throws="1"> + <source-position filename="ostree-mutable-tree.h" line="97"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="404">Tree</doc> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="405">name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_file_checksum" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="406">checksum</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="out_subdir" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="407">subdirectory</doc> + <type name="MutableTree" c:type="OstreeMutableTree**"/> + </parameter> + </parameters> + </method> + <method name="remove" + c:identifier="ostree_mutable_tree_remove" + version="2018.9" + throws="1"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="324">Remove the file or subdirectory named @name from the mutable tree @self.</doc> + <source-position filename="ostree-mutable-tree.h" line="85"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="326">Tree</doc> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="327">Name of file or subdirectory to remove</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="allow_noent" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="328">If @FALSE, an error will be thrown if @name does not exist in the tree</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="replace_file" + c:identifier="ostree_mutable_tree_replace_file" + throws="1"> + <source-position filename="ostree-mutable-tree.h" line="79"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="checksum" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_contents_checksum" + c:identifier="ostree_mutable_tree_set_contents_checksum"> + <source-position filename="ostree-mutable-tree.h" line="72"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </instance-parameter> + <parameter name="checksum" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="set_metadata_checksum" + c:identifier="ostree_mutable_tree_set_metadata_checksum"> + <source-position filename="ostree-mutable-tree.h" line="65"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </instance-parameter> + <parameter name="checksum" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="walk" c:identifier="ostree_mutable_tree_walk" throws="1"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="557">Traverse @start number of elements starting from @split_path; the +child will be returned in @out_subdir.</doc> + <source-position filename="ostree-mutable-tree.h" line="112"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="559">Tree</doc> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </instance-parameter> + <parameter name="split_path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="560">Split pathname</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="start" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="561">Descend from this number of elements in @split_path</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="out_subdir" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="562">Target parent</doc> + <type name="MutableTree" c:type="OstreeMutableTree**"/> + </parameter> + </parameters> + </method> + </class> + <record name="MutableTreeClass" + c:type="OstreeMutableTreeClass" + glib:is-gtype-struct-for="MutableTree"> + <source-position filename="ostree-mutable-tree.h" line="45"/> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <record name="MutableTreeIter" c:type="OstreeMutableTreeIter"> + <source-position filename="ostree-mutable-tree.h" line="40"/> + <field name="in_files" writable="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="iter" writable="1"> + <type name="GLib.HashTableIter" c:type="GHashTableIter"/> + </field> + </record> + <function-macro name="OBJECT_TYPE_IS_META" + c:identifier="OSTREE_OBJECT_TYPE_IS_META" + introspectable="0"> + <source-position filename="ostree-core.h" line="94"/> + <parameters> + <parameter name="t"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="90">An #OstreeObjectType</doc> + </parameter> + </parameters> + </function-macro> + <constant name="ORIGIN_TRANSIENT_GROUP" + value="libostree-transient" + c:type="OSTREE_ORIGIN_TRANSIENT_GROUP" + version="2018.3"> + <doc xml:space="preserve" + filename="ostree-deployment.h" + line="28">The name of a `GKeyFile` group for data that should not +be carried across upgrades. For more information, +see ostree_deployment_origin_remove_transient_state().</doc> + <source-position filename="ostree-deployment.h" line="37"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <enumeration name="ObjectType" c:type="OstreeObjectType"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="61">Enumeration for core object types; %OSTREE_OBJECT_TYPE_FILE is for +content, the other types are metadata.</doc> + <source-position filename="ostree-core.h" line="86"/> + <member name="file" value="1" c:identifier="OSTREE_OBJECT_TYPE_FILE"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="63">Content; regular file, symbolic link</doc> + </member> + <member name="dir_tree" + value="2" + c:identifier="OSTREE_OBJECT_TYPE_DIR_TREE"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="64">List of children (trees or files), and metadata</doc> + </member> + <member name="dir_meta" + value="3" + c:identifier="OSTREE_OBJECT_TYPE_DIR_META"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="65">Directory metadata</doc> + </member> + <member name="commit" value="4" c:identifier="OSTREE_OBJECT_TYPE_COMMIT"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="66">Toplevel object, refers to tree and dirmeta for root</doc> + </member> + <member name="tombstone_commit" + value="5" + c:identifier="OSTREE_OBJECT_TYPE_TOMBSTONE_COMMIT"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="67">Toplevel object, refers to a deleted commit</doc> + </member> + <member name="commit_meta" + value="6" + c:identifier="OSTREE_OBJECT_TYPE_COMMIT_META"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="68">Detached metadata for a commit</doc> + </member> + <member name="payload_link" + value="7" + c:identifier="OSTREE_OBJECT_TYPE_PAYLOAD_LINK"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="69">Symlink to a .file given its checksum on the payload only.</doc> + </member> + <member name="file_xattrs" + value="8" + c:identifier="OSTREE_OBJECT_TYPE_FILE_XATTRS"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="70">Detached xattrs content, for 'bare-split-xattrs' mode.</doc> + </member> + <member name="file_xattrs_link" + value="9" + c:identifier="OSTREE_OBJECT_TYPE_FILE_XATTRS_LINK"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="71">Hardlink to a .file-xattrs given the checksum of its .file object.</doc> + </member> + </enumeration> + <constant name="PATH_BOOTED" + value="/run/ostree-booted" + c:type="OSTREE_PATH_BOOTED" + version="2022.2"> + <doc xml:space="preserve" + filename="ostree-sysroot.h" + line="27">Filesystem path that is created on an ostree-booted system.</doc> + <source-position filename="ostree-sysroot.h" line="33"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="RELEASE_VERSION" + value="2" + c:type="OSTREE_RELEASE_VERSION" + version="2017.4"> + <doc xml:space="preserve" + filename="ostree-version.h" + line="37">ostree release version component (e.g. 2 if %OSTREE_VERSION is 2017.2)</doc> + <source-position filename="ostree-version.h" line="44"/> + <type name="gint" c:type="gint"/> + </constant> + <function-macro name="REPO" c:identifier="OSTREE_REPO" introspectable="0"> + <source-position filename="ostree-repo.h" line="38"/> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="REPO_FILE" + c:identifier="OSTREE_REPO_FILE" + introspectable="0"> + <source-position filename="ostree-repo-file.h" line="29"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="REPO_FILE_CLASS" + c:identifier="OSTREE_REPO_FILE_CLASS" + introspectable="0"> + <source-position filename="ostree-repo-file.h" line="30"/> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="REPO_FILE_ENUMERATOR" + c:identifier="OSTREE_REPO_FILE_ENUMERATOR" + introspectable="0"> + <source-position filename="ostree-repo-file-enumerator.h" line="29"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="REPO_FILE_ENUMERATOR_CLASS" + c:identifier="OSTREE_REPO_FILE_ENUMERATOR_CLASS" + introspectable="0"> + <source-position filename="ostree-repo-file-enumerator.h" line="30"/> + <parameters> + <parameter name="k"> + </parameter> + </parameters> + </function-macro> + <function-macro name="REPO_FILE_ENUMERATOR_GET_CLASS" + c:identifier="OSTREE_REPO_FILE_ENUMERATOR_GET_CLASS" + introspectable="0"> + <source-position filename="ostree-repo-file-enumerator.h" line="33"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <function-macro name="REPO_FILE_GET_CLASS" + c:identifier="OSTREE_REPO_FILE_GET_CLASS" + introspectable="0"> + <source-position filename="ostree-repo-file.h" line="33"/> + <parameters> + <parameter name="o"> + </parameter> + </parameters> + </function-macro> + <constant name="REPO_METADATA_REF" + value="ostree-metadata" + c:type="OSTREE_REPO_METADATA_REF" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1638">The name of a ref which is used to store metadata for the entire repository, +such as its expected update time (`ostree.summary.expires`), name, or new +GPG keys. Metadata is stored on contentless commits in the ref, and hence is +signed with the commits. + +This supersedes the additional metadata dictionary in the `summary` file +(see ostree_repo_regenerate_summary()), as the use of a ref means that the +metadata for multiple upstream repositories can be included in a single mirror +repository, disambiguating the refs using collection IDs. In order to support +peer to peer redistribution of repository metadata, repositories must set a +collection ID (ostree_repo_set_collection_id()). + +Users of OSTree may place arbitrary metadata in commits on this ref, but the +keys must be namespaced by product or developer. For example, +`exampleos.end-of-life`. The `ostree.` prefix is reserved.</doc> + <source-position filename="ostree-repo.h" line="1659"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <record name="Remote" + c:type="OstreeRemote" + version="2018.6" + glib:type-name="OstreeRemote" + glib:get-type="ostree_remote_get_type" + c:symbol-prefix="remote"> + <doc xml:space="preserve" + filename="ostree-remote.h" + line="36">This represents the configuration for a single remote repository. Currently, +remotes can only be passed around as (reference counted) opaque handles. In +future, more API may be added to create and interrogate them.</doc> + <source-position filename="ostree-types.h" line="40"/> + <method name="get_name" + c:identifier="ostree_remote_get_name" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-remote.c" + line="163">Get the human-readable name of the remote. This is what the user configured, +if the remote was explicitly configured; and will otherwise be a stable, +arbitrary, string.</doc> + <source-position filename="ostree-remote.h" line="54"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-remote.c" + line="171">remote’s name</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="remote" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-remote.c" + line="165">an #OstreeRemote</doc> + <type name="Remote" c:type="OstreeRemote*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_url" + c:identifier="ostree_remote_get_url" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-remote.c" + line="183">Get the URL from the remote.</doc> + <source-position filename="ostree-remote.h" line="57"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-remote.c" + line="189">the remote's URL</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <instance-parameter name="remote" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-remote.c" + line="185">an #OstreeRemote</doc> + <type name="Remote" c:type="OstreeRemote*"/> + </instance-parameter> + </parameters> + </method> + <method name="ref" c:identifier="ostree_remote_ref" version="2018.6"> + <doc xml:space="preserve" + filename="ostree-remote.c" + line="113">Increase the reference count on the given @remote.</doc> + <source-position filename="ostree-remote.h" line="49"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-remote.c" + line="119">a copy of @remote, for convenience</doc> + <type name="Remote" c:type="OstreeRemote*"/> + </return-value> + <parameters> + <instance-parameter name="remote" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-remote.c" + line="115">an #OstreeRemote</doc> + <type name="Remote" c:type="OstreeRemote*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="ostree_remote_unref" version="2018.6"> + <doc xml:space="preserve" + filename="ostree-remote.c" + line="132">Decrease the reference count on the given @remote and free it if the +reference count reaches 0.</doc> + <source-position filename="ostree-remote.h" line="51"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="remote" transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-remote.c" + line="134">an #OstreeRemote</doc> + <type name="Remote" c:type="OstreeRemote*"/> + </instance-parameter> + </parameters> + </method> + </record> + <class name="Repo" + c:symbol-prefix="repo" + c:type="OstreeRepo" + parent="GObject.Object" + glib:type-name="OstreeRepo" + glib:get-type="ostree_repo_get_type"> + <constructor name="new" c:identifier="ostree_repo_new"> + <source-position filename="ostree-repo.h" line="52"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1406">An accessor object for an OSTree repository located at @path</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </return-value> + <parameters> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1404">Path to a repository</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_default" c:identifier="ostree_repo_new_default"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1479">If the current working directory appears to be an OSTree +repository, create a new #OstreeRepo object for accessing it. +Otherwise use the path in the OSTREE_REPO environment variable +(if defined) or else the default system repository located at +/ostree/repo.</doc> + <source-position filename="ostree-repo.h" line="59"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1488">An accessor object for an OSTree repository located at /ostree/repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </return-value> + </constructor> + <constructor name="new_for_sysroot_path" + c:identifier="ostree_repo_new_for_sysroot_path"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1462">Creates a new #OstreeRepo instance, taking the system root path explicitly +instead of assuming "/".</doc> + <source-position filename="ostree-repo.h" line="55"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1470">An accessor object for the OSTree repository located at @repo_path.</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </return-value> + <parameters> + <parameter name="repo_path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1464">Path to a repository</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="sysroot_path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1465">Path to the system root</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + </parameters> + </constructor> + <function name="create_at" + c:identifier="ostree_repo_create_at" + version="2017.10" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2896">This is a file-descriptor relative version of ostree_repo_create(). +Create the underlying structure on disk for the repository, and call +ostree_repo_open_at() on the result, preparing it for use. + +If a repository already exists at @dfd + @path (defined by an `objects/` +subdirectory existing), then this function will simply call +ostree_repo_open_at(). In other words, this function cannot be used to change +the mode or configuration (`repo/config`) of an existing repo. + +The @options dict may contain: + + - collection-id: s: Set as collection ID in repo/config (Since 2017.9)</doc> + <source-position filename="ostree-repo.h" line="100"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2918">A new OSTree repository reference</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </return-value> + <parameters> + <parameter name="dfd" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2898">Directory fd</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2899">Path</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2900">The mode to store the repository in</doc> + <type name="RepoMode" c:type="OstreeRepoMode"/> + </parameter> + <parameter name="options" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2901">a{sv}: See below for accepted keys</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2902">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="mode_from_string" + c:identifier="ostree_repo_mode_from_string" + throws="1"> + <source-position filename="ostree-repo.h" line="44"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2720">a repo mode as a string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_mode" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2721">the corresponding #OstreeRepoMode</doc> + <type name="RepoMode" c:type="OstreeRepoMode*"/> + </parameter> + </parameters> + </function> + <function name="open_at" + c:identifier="ostree_repo_open_at" + version="2017.10" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1427">This combines ostree_repo_new() (but using fd-relative access) with +ostree_repo_open(). Use this when you know you should be operating on an +already extant repository. If you want to create one, use ostree_repo_create_at().</doc> + <source-position filename="ostree-repo.h" line="68"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1436">An accessor object for an OSTree repository located at @dfd + @path</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </return-value> + <parameters> + <parameter name="dfd" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1429">Directory fd</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1430">Path</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="pull_default_console_progress_changed" + c:identifier="ostree_repo_pull_default_console_progress_changed"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5121">Convenient "changed" callback for use with +ostree_async_progress_new_and_connect() when pulling from a remote +repository. + +Depending on the state of the #OstreeAsyncProgress, either displays a +custom status message, or else outstanding fetch progress in bytes/sec, +or else outstanding content or metadata writes to the repository in +number of objects. + +Compatibility note: this function previously assumed that @user_data +was a pointer to a #GSConsole instance. This is no longer the case, +and @user_data is ignored.</doc> + <source-position filename="ostree-repo.h" line="1409"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="progress" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5123">Async progress</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5124">User data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="traverse_new_parents" + c:identifier="ostree_repo_traverse_new_parents" + version="2018.5"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="295">This hash table is a mapping from #GVariant which can be accessed +via ostree_object_name_deserialize() to a #GVariant containing either +a similar #GVariant or and array of them, listing the parents of the key.</doc> + <source-position filename="ostree-repo.h" line="1164"/> + <return-value transfer-ownership="container"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="302">A new hash table</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="GLib.Variant"/> + <type name="GLib.Variant"/> + </type> + </return-value> + </function> + <function name="traverse_new_reachable" + c:identifier="ostree_repo_traverse_new_reachable"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="280">This hash table is a set of #GVariant which can be accessed via +ostree_object_name_deserialize().</doc> + <source-position filename="ostree-repo.h" line="1161"/> + <return-value transfer-ownership="container"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="286">A new hash table</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="GLib.Variant"/> + <type name="GLib.Variant"/> + </type> + </return-value> + </function> + <function name="traverse_parents_get_commits" + c:identifier="ostree_repo_traverse_parents_get_commits" + version="2018.5"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="346">Gets all the commits that a certain object belongs to, as recorded +by a parents table gotten from ostree_repo_traverse_commit_union_with_parents.</doc> + <source-position filename="ostree-repo.h" line="1167"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="352">An array of checksums for +the commits the key belongs to.</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <parameter name="parents" transfer-ownership="none"> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="object" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <method name="abort_transaction" + c:identifier="ostree_repo_abort_transaction" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2381">Abort the active transaction; any staged objects and ref changes will be +discarded. You *must* invoke this if you have chosen not to invoke +ostree_repo_commit_transaction(). Calling this function when not in a +transaction will do nothing and return successfully.</doc> + <source-position filename="ostree-repo.h" line="327"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2383">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2384">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="add_gpg_signature_summary" + c:identifier="ostree_repo_add_gpg_signature_summary" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5492">Add a GPG signature to a summary file.</doc> + <source-position filename="ostree-repo.h" line="1501"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5494">Self</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="key_id" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5495">NULL-terminated array of GPG keys.</doc> + <array c:type="const gchar**"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="homedir" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5496">GPG home directory, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5497">A #GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="append_gpg_signature" + c:identifier="ostree_repo_append_gpg_signature" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5271">Append a GPG signature to a commit.</doc> + <source-position filename="ostree-repo.h" line="1508"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5273">Self</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="commit_checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5274">SHA256 of given commit to sign</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="signature_bytes" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5275">Signature data</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5276">A #GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="checkout_at" + c:identifier="ostree_repo_checkout_at" + version="2016.8" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1327">Similar to ostree_repo_checkout_tree(), but uses directory-relative +paths for the destination, uses a new `OstreeRepoCheckoutAtOptions`, +and takes a commit checksum and optional subpath pair, rather than +requiring use of `GFile` APIs for the caller. + +It also replaces ostree_repo_checkout_at() which was not safe to +use with GObject introspection. + +Note in addition that unlike ostree_repo_checkout_tree(), the +default is not to use the repository-internal uncompressed objects +cache.</doc> + <source-position filename="ostree-repo.h" line="1020"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1329">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="options" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1330">Options</doc> + <type name="RepoCheckoutAtOptions" + c:type="OstreeRepoCheckoutAtOptions*"/> + </parameter> + <parameter name="destination_dfd" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1331">Directory FD for destination</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="destination_path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1332">Directory for destination</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="commit" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1333">Checksum for commit</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1334">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="checkout_gc" + c:identifier="ostree_repo_checkout_gc" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1466">Call this after finishing a succession of checkout operations; it +will delete any currently-unused uncompressed objects from the +cache.</doc> + <source-position filename="ostree-repo.h" line="1029"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1468">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1469">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="checkout_tree" + c:identifier="ostree_repo_checkout_tree" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1245">Check out @source into @destination, which must live on the +physical filesystem. @source may be any subdirectory of a given +commit. The @mode and @overwrite_mode allow control over how the +files are checked out.</doc> + <source-position filename="ostree-repo.h" line="935"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1247">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1248">Options controlling all files</doc> + <type name="RepoCheckoutMode" c:type="OstreeRepoCheckoutMode"/> + </parameter> + <parameter name="overwrite_mode" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1249">Whether or not to overwrite files</doc> + <type name="RepoCheckoutOverwriteMode" + c:type="OstreeRepoCheckoutOverwriteMode"/> + </parameter> + <parameter name="destination" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1250">Place tree here</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1251">Source tree</doc> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </parameter> + <parameter name="source_info" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1252">Source info</doc> + <type name="Gio.FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1253">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="checkout_tree_at" + c:identifier="ostree_repo_checkout_tree_at" + introspectable="0" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1284">Similar to ostree_repo_checkout_tree(), but uses directory-relative +paths for the destination, uses a new `OstreeRepoCheckoutAtOptions`, +and takes a commit checksum and optional subpath pair, rather than +requiring use of `GFile` APIs for the caller. + +Note in addition that unlike ostree_repo_checkout_tree(), the +default is not to use the repository-internal uncompressed objects +cache. + +This function is deprecated. Use ostree_repo_checkout_at() instead.</doc> + <source-position filename="ostree-repo-deprecated.h" line="61"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1286">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="options" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1287">Options</doc> + <type name="RepoCheckoutOptions" + c:type="OstreeRepoCheckoutOptions*"/> + </parameter> + <parameter name="destination_dfd" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1288">Directory FD for destination</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="destination_path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1289">Directory for destination</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="commit" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1290">Checksum for commit</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1291">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="commit_transaction" + c:identifier="ostree_repo_commit_transaction" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2281">Complete the transaction. Any refs set with +ostree_repo_transaction_set_ref() or +ostree_repo_transaction_set_refspec() will be written out. + +Note that if multiple threads are performing writes, all such threads must +have terminated before this function is invoked. + +Locking: Releases `shared` lock acquired by `ostree_repo_prepare_transaction()` +Multithreading: This function is *not* MT safe; only one transaction can be +active at a time.</doc> + <source-position filename="ostree-repo.h" line="321"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2283">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="out_stats" + direction="out" + caller-allocates="1" + transfer-ownership="none" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2284">A set of statistics of things +that happened during this transaction.</doc> + <type name="RepoTransactionStats" + c:type="OstreeRepoTransactionStats*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2286">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="copy_config" c:identifier="ostree_repo_copy_config"> + <source-position filename="ostree-repo.h" line="143"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1610">A newly-allocated copy of the repository config</doc> + <type name="GLib.KeyFile" c:type="GKeyFile*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + </parameters> + </method> + <method name="create" c:identifier="ostree_repo_create" throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2848">Create the underlying structure on disk for the repository, and call +ostree_repo_open() on the result, preparing it for use. + +Since version 2016.8, this function will succeed on an existing +repository, and finish creating any necessary files in a partially +created repository. However, this function cannot change the mode +of an existing repository, and will silently ignore an attempt to +do so. + +Since 2017.9, "existing repository" is defined by the existence of an +`objects` subdirectory. + +This function predates ostree_repo_create_at(). It is an error to call +this function on a repository initialized via ostree_repo_open_at().</doc> + <source-position filename="ostree-repo.h" line="95"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2850">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2851">The mode to store the repository in</doc> + <type name="RepoMode" c:type="OstreeRepoMode"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2852">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="delete_object" + c:identifier="ostree_repo_delete_object" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4565">Remove the object of type @objtype with checksum @sha256 +from the repository. An error of type %G_IO_ERROR_NOT_FOUND +is thrown if the object does not exist.</doc> + <source-position filename="ostree-repo.h" line="637"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4567">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4568">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="sha256" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4569">Checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4570">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="equal" c:identifier="ostree_repo_equal" version="2017.12"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3796">Check whether two opened repositories are the same on disk: if their root +directories are the same inode. If @a or @b are not open yet (due to +ostree_repo_open() not being called on them yet), %FALSE will be returned.</doc> + <source-position filename="ostree-repo.h" line="129"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3805">%TRUE if @a and @b are the same repository on disk, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="a" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3798">an #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="b" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3799">an #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + </parameters> + </method> + <method name="export_tree_to_archive" + c:identifier="ostree_repo_export_tree_to_archive" + introspectable="0" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="1257">Import an archive file @archive into the repository, and write its +file structure to @mtree.</doc> + <source-position filename="ostree-repo.h" line="858"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="1259">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="opts" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="1260">Options controlling conversion</doc> + <type name="RepoExportArchiveOptions" + c:type="OstreeRepoExportArchiveOptions*"/> + </parameter> + <parameter name="root" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="1261">An #OstreeRepoFile for the base directory</doc> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </parameter> + <parameter name="archive" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="1262">A `struct archive`, but specified as void to avoid a dependency on the libarchive headers</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="1263">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="find_remotes_async" + c:identifier="ostree_repo_find_remotes_async" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="5427">Find reachable remote URIs which claim to provide any of the given named +@refs. This will search for configured remotes (#OstreeRepoFinderConfig), +mounted volumes (#OstreeRepoFinderMount) and (if enabled at compile time) +local network peers (#OstreeRepoFinderAvahi). In order to use a custom +configuration of #OstreeRepoFinder instances, call +ostree_repo_finder_resolve_all_async() on them individually. + +Any remote which is found and which claims to support any of the given @refs +will be returned in the results. It is possible that a remote claims to +support a given ref, but turns out not to — it is not possible to verify this +until ostree_repo_pull_from_remotes_async() is called. + +The returned results will be sorted with the most useful first — this is +typically the remote which claims to provide the most of @refs, at the lowest +latency. + +Each result contains a list of the subset of @refs it claims to provide. It +is possible for a non-empty list of results to be returned, but for some of +@refs to not be listed in any of the results. Callers must check for this. + +Pass the results to ostree_repo_pull_from_remotes_async() to pull the given @refs +from those remotes. + +The following @options are currently defined: + + * `override-commit-ids` (`as`): Array of specific commit IDs to fetch. The nth + commit ID applies to the nth ref, so this must be the same length as @refs, if + provided. + * `n-network-retries` (`u`): Number of times to retry each download on + receiving a transient network error, such as a socket timeout; default is + 5, 0 means return errors without retrying. Since: 2018.6 + +@finders must be a non-empty %NULL-terminated array of the #OstreeRepoFinder +instances to use, or %NULL to use the system default set of finders, which +will typically be all available finders using their default options (but +this is not guaranteed). + +GPG verification of commits will be used unconditionally. + +This will use the thread-default #GMainContext, but will not iterate it.</doc> + <source-position filename="ostree-repo.h" line="1368"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="5429">an #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="refs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="5430">non-empty array of collection–ref pairs to find remotes for</doc> + <array c:type="const OstreeCollectionRef* const*"> + <type name="CollectionRef" c:type="OstreeCollectionRef*"/> + </array> + </parameter> + <parameter name="options" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="5431">a GVariant `a{sv}` with an extensible set of flags</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="finders" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="5432">non-empty array of + #OstreeRepoFinder instances to use, or %NULL to use the system defaults</doc> + <array c:type="OstreeRepoFinder**"> + <type name="RepoFinder" c:type="OstreeRepoFinder*"/> + </array> + </parameter> + <parameter name="progress" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="5434">an #OstreeAsyncProgress to update with the operation’s + progress, or %NULL</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="5436">a #GCancellable, or %NULL</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" + transfer-ownership="none" + nullable="1" + allow-none="1" + scope="async" + closure="6"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="5437">asynchronous completion callback</doc> + <type name="Gio.AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="5438">data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="find_remotes_finish" + c:identifier="ostree_repo_find_remotes_finish" + version="2018.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6226">Finish an asynchronous pull operation started with +ostree_repo_find_remotes_async().</doc> + <source-position filename="ostree-repo.h" line="1377"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6235">a potentially empty array + of #OstreeRepoFinderResults, followed by a %NULL terminator element; or + %NULL on error</doc> + <array c:type="OstreeRepoFinderResult**"> + <type name="RepoFinderResult" c:type="OstreeRepoFinderResult*"/> + </array> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6228">an #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6229">the asynchronous result</doc> + <type name="Gio.AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="fsck_object" + c:identifier="ostree_repo_fsck_object" + version="2017.15" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4681">Verify consistency of the object; this performs checks only relevant to the +immediate object itself, such as checksumming. This API call will not itself +traverse metadata objects for example.</doc> + <source-position filename="ostree-repo.h" line="644"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4683">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4684">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="sha256" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4685">Checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4686">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="get_bootloader" + c:identifier="ostree_repo_get_bootloader" + version="2019.2"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6674">Get the bootloader configured. See the documentation for the +"sysroot.bootloader" config key.</doc> + <source-position filename="ostree-repo.h" line="118"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6681">bootloader configuration for the sysroot</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6676">an #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_collection_id" + c:identifier="ostree_repo_get_collection_id" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6602">Get the collection ID of this repository. See [collection IDs][collection-ids].</doc> + <source-position filename="ostree-repo.h" line="108"/> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6608">collection ID for the repository</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6604">an #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_config" c:identifier="ostree_repo_get_config"> + <source-position filename="ostree-repo.h" line="140"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1595">The repository configuration; do not modify</doc> + <type name="GLib.KeyFile" c:type="GKeyFile*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_default_repo_finders" + c:identifier="ostree_repo_get_default_repo_finders" + version="2018.9"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6655">Get the set of default repo finders configured. See the documentation for +the "core.default-repo-finders" config key.</doc> + <source-position filename="ostree-repo.h" line="115"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6662"> + %NULL-terminated array of strings.</doc> + <array c:type="const gchar* const*"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6657">an #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_dfd" + c:identifier="ostree_repo_get_dfd" + version="2016.4"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3747">In some cases it's useful for applications to access the repository +directly; for example, writing content into `repo/tmp` ensures it's +on the same filesystem. Another case is detecting the mtime on the +repository (to see whether a ref was written).</doc> + <source-position filename="ostree-repo.h" line="124"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3756">File descriptor for repository root - owned by @self</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3749">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_disable_fsync" + c:identifier="ostree_repo_get_disable_fsync"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3694">For more information see ostree_repo_set_disable_fsync().</doc> + <source-position filename="ostree-repo.h" line="85"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3700">Whether or not fsync() is enabled for this repo.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3696">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_min_free_space_bytes" + c:identifier="ostree_repo_get_min_free_space_bytes" + version="2018.9" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3830">Determine the number of bytes of free disk space that are reserved according +to the repo config and return that number in @out_reserved_bytes. See the +documentation for the core.min-free-space-size and +core.min-free-space-percent repo config options.</doc> + <source-position filename="ostree-repo.h" line="136"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3841">%TRUE on success, %FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3832">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="out_reserved_bytes" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3833">Location to store the result</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + </parameters> + </method> + <method name="get_mode" c:identifier="ostree_repo_get_mode"> + <source-position filename="ostree-repo.h" line="133"/> + <return-value transfer-ownership="none"> + <type name="RepoMode" c:type="OstreeRepoMode"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_parent" c:identifier="ostree_repo_get_parent"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3857">Before this function can be used, ostree_repo_init() must have been +called.</doc> + <source-position filename="ostree-repo.h" line="243"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3864">Parent repository, or %NULL if none</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3859">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_path" c:identifier="ostree_repo_get_path"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3725">Note that since the introduction of ostree_repo_open_at(), this function may +return a process-specific path in `/proc` if the repository was created using +that API. In general, you should avoid use of this API.</doc> + <source-position filename="ostree-repo.h" line="121"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3733">Path to repo</doc> + <type name="Gio.File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3727">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_remote_boolean_option" + c:identifier="ostree_repo_get_remote_boolean_option" + version="2016.5" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1102">OSTree remotes are represented by keyfile groups, formatted like: +`[remote "remotename"]`. This function returns a value named @option_name +underneath that group, and returns it as a boolean. +If the option is not set, @out_value will be set to @default_value. If an +error is returned, @out_value will be set to %FALSE.</doc> + <source-position filename="ostree-repo.h" line="217"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1117">%TRUE on success, otherwise %FALSE with @error set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1104">A OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="remote_name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1105">Name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="option_name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1106">Option</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="default_value" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1107">Value returned if @option_name is not present</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="out_value" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1108">location to store the result.</doc> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + </parameters> + </method> + <method name="get_remote_list_option" + c:identifier="ostree_repo_get_remote_list_option" + version="2016.5" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1024">OSTree remotes are represented by keyfile groups, formatted like: +`[remote "remotename"]`. This function returns a value named @option_name +underneath that group, and returns it as a zero terminated array of strings. +If the option is not set, or if an error is returned, @out_value will be set +to %NULL.</doc> + <source-position filename="ostree-repo.h" line="210"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1040">%TRUE on success, otherwise %FALSE with @error set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1026">A OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="remote_name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1027">Name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="option_name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1028">Option</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_value" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1029">location to store the list + of strings. The list should be freed with + g_strfreev().</doc> + <array c:type="char***"> + <type name="utf8" c:type="char**"/> + </array> + </parameter> + </parameters> + </method> + <method name="get_remote_option" + c:identifier="ostree_repo_get_remote_option" + version="2016.5" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="946">OSTree remotes are represented by keyfile groups, formatted like: +`[remote "remotename"]`. This function returns a value named @option_name +underneath that group, or @default_value if the remote exists but not the +option name. If an error is returned, @out_value will be set to %NULL.</doc> + <source-position filename="ostree-repo.h" line="202"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="960">%TRUE on success, otherwise %FALSE with @error set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="948">A OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="remote_name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="949">Name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="option_name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="950">Option</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="default_value" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="951">Value returned if @option_name is not present</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_value" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="952">Return location for value</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="gpg_sign_data" + c:identifier="ostree_repo_gpg_sign_data" + version="2020.8" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5558">Sign the given @data with the specified keys in @key_id. Similar to +ostree_repo_add_gpg_signature_summary() but can be used on any +data. + +You can use ostree_repo_gpg_verify_data() to verify the signatures.</doc> + <source-position filename="ostree-repo.h" line="1515"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5575">@TRUE if @data has been signed successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5560">Self</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5561">Data as a #GBytes</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="old_signatures" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5562">Existing signatures to append to (or %NULL)</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="key_id" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5563">NULL-terminated array of GPG keys.</doc> + <array c:type="const gchar**"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="homedir" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5564">GPG home directory, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="out_signatures" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5565">in case of success will contain signature</doc> + <type name="GLib.Bytes" c:type="GBytes**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5566">A #GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="gpg_verify_data" + c:identifier="ostree_repo_gpg_verify_data" + version="2016.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5989">Verify @signatures for @data using GPG keys in the keyring for +@remote_name, and return an #OstreeGpgVerifyResult. + +The @remote_name parameter can be %NULL. In that case it will do +the verifications using GPG keys in the keyrings of all remotes.</doc> + <source-position filename="ostree-repo.h" line="1541"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6006">an #OstreeGpgVerifyResult, or %NULL on error</doc> + <type name="GpgVerifyResult" c:type="OstreeGpgVerifyResult*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5991">Repository</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="remote_name" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5992">Name of remote</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5993">Data as a #GBytes</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="signatures" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5994">Signatures as a #GBytes</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="keyringdir" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5995">Path to directory GPG keyrings; overrides built-in default if given</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="extra_keyring" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5996">Path to additional keyring file (not a directory)</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5997">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="has_object" + c:identifier="ostree_repo_has_object" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4523">Set @out_have_object to %TRUE if @self contains the given object; +%FALSE otherwise.</doc> + <source-position filename="ostree-repo.h" line="384"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4535">%FALSE if an unexpected error occurred, %TRUE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4525">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4526">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4527">ASCII SHA256 checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_have_object" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4528">%TRUE if repository contains object</doc> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4529">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="hash" c:identifier="ostree_repo_hash" version="2017.12"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3766">Calculate a hash value for the given open repository, suitable for use when +putting it into a hash table. It is an error to call this on an #OstreeRepo +which is not yet open, as a persistent hash value cannot be calculated until +the repository is open and the inode of its root directory has been loaded. + +This function does no I/O.</doc> + <source-position filename="ostree-repo.h" line="127"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3777">hash value for the #OstreeRepo</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3768">an #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + </parameters> + </method> + <method name="import_archive_to_mtree" + c:identifier="ostree_repo_import_archive_to_mtree" + introspectable="0" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="843">Import an archive file @archive into the repository, and write its +file structure to @mtree.</doc> + <source-position filename="ostree-repo.h" line="828"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="845">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="opts" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="846">Options structure, ensure this is zeroed, then set specific variables</doc> + <type name="RepoImportArchiveOptions" + c:type="OstreeRepoImportArchiveOptions*"/> + </parameter> + <parameter name="archive" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="847">Really this is "struct archive*"</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + <parameter name="mtree" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="848">The #OstreeMutableTree to write to</doc> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </parameter> + <parameter name="modifier" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="849">Optional commit modifier</doc> + <type name="RepoCommitModifier" + c:type="OstreeRepoCommitModifier*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="850">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="import_object_from" + c:identifier="ostree_repo_import_object_from" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4708">Copy object named by @objtype and @checksum into @self from the +source repository @source. If both repositories are of the same +type and on the same filesystem, this will simply be a fast Unix +hard link operation. + +Otherwise, a copy will be performed.</doc> + <source-position filename="ostree-repo.h" line="621"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4710">Destination repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4711">Source repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4712">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4713">checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4714">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="import_object_from_with_trust" + c:identifier="ostree_repo_import_object_from_with_trust" + version="2016.5" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4737">Copy object named by @objtype and @checksum into @self from the +source repository @source. If @trusted is %TRUE and both +repositories are of the same type and on the same filesystem, +this will simply be a fast Unix hard link operation. + +Otherwise, a copy will be performed.</doc> + <source-position filename="ostree-repo.h" line="628"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4739">Destination repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="source" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4740">Source repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4741">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4742">checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="trusted" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4743">If %TRUE, assume the source repo is valid and trusted</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4744">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="is_system" c:identifier="ostree_repo_is_system"> + <source-position filename="ostree-repo.h" line="88"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1517">%TRUE if this repository is the root-owned system global repository</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1515">Repository</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_writable" + c:identifier="ostree_repo_is_writable" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1547">Returns whether the repository is writable by the current user. +If the repository is not writable, the @error indicates why.</doc> + <source-position filename="ostree-repo.h" line="91"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1555">%TRUE if this repository is writable</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1549">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + </parameters> + </method> + <method name="list_collection_refs" + c:identifier="ostree_repo_list_collection_refs" + version="2018.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="1250">List all local, mirrored, and remote refs, mapping them to the commit +checksums they currently point to in @out_all_refs. If @match_collection_id +is specified, the results will be limited to those with an equal collection +ID. + +#OstreeCollectionRefs are guaranteed to be returned with their collection ID +set to a non-%NULL value; so no refs from `refs/heads` will be listed if no +collection ID is configured for the repository +(ostree_repo_get_collection_id()). + +If you want to exclude refs from `refs/remotes`, use +%OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_REMOTES in @flags. Similarly use +%OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_MIRRORS to exclude refs from +`refs/mirrors`.</doc> + <source-position filename="ostree-repo.h" line="1401"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="1275">%TRUE on success, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="1252">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="match_collection_id" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="1253">If non-%NULL, only list refs from this collection</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_all_refs" + direction="out" + caller-allocates="0" + transfer-ownership="container"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="1254"> + Mapping from collection–ref to checksum</doc> + <type name="GLib.HashTable" c:type="GHashTable**"> + <type name="CollectionRef"/> + <type name="utf8"/> + </type> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="1256">Options controlling listing behavior</doc> + <type name="RepoListRefsExtFlags" + c:type="OstreeRepoListRefsExtFlags"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="1257">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="list_commit_objects_starting_with" + c:identifier="ostree_repo_list_commit_objects_starting_with" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4931">This function synchronously enumerates all commit objects starting +with @start, returning data in @out_commits.</doc> + <source-position filename="ostree-repo.h" line="1071"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4943">%TRUE on success, %FALSE on error, and @error will be set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4933">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="start" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4934">List commits starting with this checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_commits" + direction="out" + caller-allocates="0" + transfer-ownership="container"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4935"> +Map of serialized commit name to variant data</doc> + <type name="GLib.HashTable" c:type="GHashTable**"> + <type name="GLib.Variant"/> + <type name="GLib.Variant"/> + </type> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4937">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="list_objects" + c:identifier="ostree_repo_list_objects" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4877">This function synchronously enumerates all objects in the +repository, returning data in @out_objects. @out_objects +maps from keys returned by ostree_object_name_serialize() +to #GVariant values of type %OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE.</doc> + <source-position filename="ostree-repo.h" line="1064"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4891">%TRUE on success, %FALSE on error, and @error will be set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4879">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4880">Flags controlling enumeration</doc> + <type name="RepoListObjectsFlags" + c:type="OstreeRepoListObjectsFlags"/> + </parameter> + <parameter name="out_objects" + direction="out" + caller-allocates="0" + transfer-ownership="container"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4881"> +Map of serialized object name to variant data</doc> + <type name="GLib.HashTable" c:type="GHashTable**"> + <type name="GLib.Variant"/> + <type name="GLib.Variant"/> + </type> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4883">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="list_refs" c:identifier="ostree_repo_list_refs" throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="811">If @refspec_prefix is %NULL, list all local and remote refspecs, +with their current values in @out_all_refs. Otherwise, only list +refspecs which have @refspec_prefix as a prefix. + +@out_all_refs will be returned as a mapping from refspecs (including the +remote name) to checksums. If @refspec_prefix is non-%NULL, it will be +removed as a prefix from the hash table keys.</doc> + <source-position filename="ostree-repo.h" line="531"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="813">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="refspec_prefix" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="814">Only list refs which match this prefix</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_all_refs" + direction="out" + caller-allocates="0" + transfer-ownership="container"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="815"> + Mapping from refspec to checksum</doc> + <type name="GLib.HashTable" c:type="GHashTable**"> + <type name="utf8"/> + <type name="utf8"/> + </type> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="817">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="list_refs_ext" + c:identifier="ostree_repo_list_refs_ext" + version="2016.4" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="841">If @refspec_prefix is %NULL, list all local and remote refspecs, +with their current values in @out_all_refs. Otherwise, only list +refspecs which have @refspec_prefix as a prefix. + +@out_all_refs will be returned as a mapping from refspecs (including the +remote name) to checksums. Differently from ostree_repo_list_refs(), the +@refspec_prefix will not be removed from the refspecs in the hash table.</doc> + <source-position filename="ostree-repo.h" line="552"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="843">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="refspec_prefix" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="844">Only list refs which match this prefix</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_all_refs" + direction="out" + caller-allocates="0" + transfer-ownership="container"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="845"> + Mapping from refspec to checksum</doc> + <type name="GLib.HashTable" c:type="GHashTable**"> + <type name="utf8"/> + <type name="utf8"/> + </type> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="847">Options controlling listing behavior</doc> + <type name="RepoListRefsExtFlags" + c:type="OstreeRepoListRefsExtFlags"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="848">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="list_static_delta_indexes" + c:identifier="ostree_repo_list_static_delta_indexes" + version="2020.8" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="169">This function synchronously enumerates all static delta indexes in the +repository, returning its result in @out_indexes.</doc> + <source-position filename="ostree-repo.h" line="1084"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="171">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="out_indexes" + direction="out" + caller-allocates="0" + transfer-ownership="container"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="172">String name of delta indexes (checksum)</doc> + <array name="GLib.PtrArray" c:type="GPtrArray**"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="173">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="list_static_delta_names" + c:identifier="ostree_repo_list_static_delta_names" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="78">This function synchronously enumerates all static deltas in the +repository, returning its result in @out_deltas.</doc> + <source-position filename="ostree-repo.h" line="1078"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="80">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="out_deltas" + direction="out" + caller-allocates="0" + transfer-ownership="container"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="81">String name of deltas (checksum-checksum.delta)</doc> + <array name="GLib.PtrArray" c:type="GPtrArray**"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="82">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="load_commit" + c:identifier="ostree_repo_load_commit" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4853">A version of ostree_repo_load_variant() specialized to commits, +capable of returning extended state information. Currently +the only extended state is %OSTREE_REPO_COMMIT_STATE_PARTIAL, which +means that only a sub-path of the commit is available.</doc> + <source-position filename="ostree-repo.h" line="588"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4855">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4856">Commit checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_commit" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4857">Commit</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + <parameter name="out_state" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4858">Commit state</doc> + <type name="RepoCommitState" c:type="OstreeRepoCommitState*"/> + </parameter> + </parameters> + </method> + <method name="load_file" c:identifier="ostree_repo_load_file" throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4362">Load content object, decomposing it into three parts: the actual +content (for regular files), the metadata, and extended attributes.</doc> + <source-position filename="ostree-repo.h" line="595"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4364">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4365">ASCII SHA256 checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_input" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4366">File content</doc> + <type name="Gio.InputStream" c:type="GInputStream**"/> + </parameter> + <parameter name="out_file_info" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4367">File information</doc> + <type name="Gio.FileInfo" c:type="GFileInfo**"/> + </parameter> + <parameter name="out_xattrs" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4368">Extended attributes</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4369">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="load_object_stream" + c:identifier="ostree_repo_load_object_stream" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4423">Load object as a stream; useful when copying objects between +repositories.</doc> + <source-position filename="ostree-repo.h" line="604"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4425">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4426">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4427">ASCII SHA256 checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_input" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4428">Stream for object</doc> + <type name="Gio.InputStream" c:type="GInputStream**"/> + </parameter> + <parameter name="out_size" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4429">Length of @out_input</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4430">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="load_variant" + c:identifier="ostree_repo_load_variant" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4831">Load the metadata object @sha256 of type @objtype, storing the +result in @out_variant.</doc> + <source-position filename="ostree-repo.h" line="574"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4833">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4834">Expected object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="sha256" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4835">Checksum string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_variant" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4836">Metadata object</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + </parameters> + </method> + <method name="load_variant_if_exists" + c:identifier="ostree_repo_load_variant_if_exists" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4807">Attempt to load the metadata object @sha256 of type @objtype if it +exists, storing the result in @out_variant. If it doesn't exist, +@out_variant will be set to %NULL and the function will still +return TRUE.</doc> + <source-position filename="ostree-repo.h" line="581"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4809">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4810">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="sha256" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4811">ASCII checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_variant" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4812">Metadata</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + </parameters> + </method> + <method name="lock_pop" + c:identifier="ostree_repo_lock_pop" + version="2021.3" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="549">Release a lock of type @lock_type from the lock state. If the lock state +becomes empty, the repository is unlocked. Otherwise, the lock state only +changes when transitioning from an exclusive lock back to a shared lock. The +requested @lock_type must be the same type that was requested in the call to +ostree_repo_lock_push(). It is a programmer error if these do not match and +the program may abort if the lock would reach an invalid state. + +ostree_repo_lock_pop() waits for the lock depending on the repository's +lock-timeout-secs configuration. When lock-timeout-secs is -1, a blocking lock is +attempted. Otherwise, the lock is removed non-blocking and +ostree_repo_lock_pop() will sleep synchronously up to lock-timeout-secs seconds +attempting to remove the lock. If the lock cannot be removed within the +timeout, a %G_IO_ERROR_WOULD_BLOCK error is returned. + +If @self is not writable by the user, then no unlocking is attempted and +%TRUE is returned.</doc> + <source-position filename="ostree-repo.h" line="1608"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="573">%TRUE on success, otherwise %FALSE with @error set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="551">a #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="lock_type" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="552">the type of lock to release</doc> + <type name="RepoLockType" c:type="OstreeRepoLockType"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="553">a #GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="lock_push" + c:identifier="ostree_repo_lock_push" + version="2021.3" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="454">Takes a lock on the repository and adds it to the lock state. If @lock_type +is %OSTREE_REPO_LOCK_SHARED, a shared lock is taken. If @lock_type is +%OSTREE_REPO_LOCK_EXCLUSIVE, an exclusive lock is taken. The actual lock +state is only changed when locking a previously unlocked repository or +upgrading the lock from shared to exclusive. If the requested lock type is +unchanged or would represent a downgrade (exclusive to shared), the lock +state is not changed. + +ostree_repo_lock_push() waits for the lock depending on the repository's +lock-timeout-secs configuration. When lock-timeout-secs is -1, a blocking lock is +attempted. Otherwise, the lock is taken non-blocking and +ostree_repo_lock_push() will sleep synchronously up to lock-timeout-secs seconds +attempting to acquire the lock. If the lock cannot be acquired within the +timeout, a %G_IO_ERROR_WOULD_BLOCK error is returned. + +If @self is not writable by the user, then no locking is attempted and +%TRUE is returned.</doc> + <source-position filename="ostree-repo.h" line="1603"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="479">%TRUE on success, otherwise %FALSE with @error set</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="456">a #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="lock_type" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="457">the type of lock to acquire</doc> + <type name="RepoLockType" c:type="OstreeRepoLockType"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="458">a #GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="mark_commit_partial" + c:identifier="ostree_repo_mark_commit_partial" + version="2017.15" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2045">Commits in the "partial" state do not have all their child objects +written. This occurs in various situations, such as during a pull, +but also if a "subpath" pull is used, as well as "commit only" +pulls. + +This function is used by ostree_repo_pull_with_options(); you +should use this if you are implementing a different type of transport.</doc> + <source-position filename="ostree-repo.h" line="332"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2047">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2048">Commit SHA-256</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="is_partial" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2049">Whether or not this commit is partial</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="mark_commit_partial_reason" + c:identifier="ostree_repo_mark_commit_partial_reason" + version="2019.4" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="1994">Allows the setting of a reason code for a partial commit. Presently +it only supports setting reason bitmask to +OSTREE_REPO_COMMIT_STATE_FSCK_PARTIAL, or +OSTREE_REPO_COMMIT_STATE_NORMAL. This will allow successive ostree +fsck operations to exit properly with an error code if the +repository has been truncated as a result of fsck trying to repair +it.</doc> + <source-position filename="ostree-repo.h" line="338"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="1996">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="1997">Commit SHA-256</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="is_partial" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="1998">Whether or not this commit is partial</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="in_state" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="1999">Reason bitmask for partial commit</doc> + <type name="RepoCommitState" c:type="OstreeRepoCommitState"/> + </parameter> + </parameters> + </method> + <method name="open" c:identifier="ostree_repo_open" throws="1"> + <source-position filename="ostree-repo.h" line="62"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="prepare_transaction" + c:identifier="ostree_repo_prepare_transaction" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="1649">Starts or resumes a transaction. In order to write to a repo, you +need to start a transaction. You can complete the transaction with +ostree_repo_commit_transaction(), or abort the transaction with +ostree_repo_abort_transaction(). + +Currently, transactions may result in partial commits or data in the target +repository if interrupted during ostree_repo_commit_transaction(), and +further writing refs is also not currently atomic. + +There can be at most one transaction active on a repo at a time per instance +of `OstreeRepo`; however, it is safe to have multiple threads writing objects +on a single `OstreeRepo` instance as long as their lifetime is bounded by the +transaction. + +Locking: Acquires a `shared` lock; release via commit or abort +Multithreading: This function is *not* MT safe; only one transaction can be +active at a time.</doc> + <source-position filename="ostree-repo.h" line="315"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="1651">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="out_transaction_resume" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="1652">Whether this transaction +is resuming from a previous one. This is a legacy state, now OSTree +pulls use per-commit `state/.commitpartial` files.</doc> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="1655">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="prune" c:identifier="ostree_repo_prune" throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="382">Delete content from the repository. By default, this function will +only delete "orphaned" objects not referred to by any commit. This +can happen during a local commit operation, when we have written +content objects but not saved the commit referencing them. + +However, if %OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY is provided, instead +of traversing all commits, only refs will be used. Particularly +when combined with @depth, this is a convenient way to delete +history from the repository. + +Use the %OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE to just determine +statistics on objects that would be deleted, without actually +deleting them. + +Locking: exclusive</doc> + <source-position filename="ostree-repo.h" line="1281"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="384">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="385">Options controlling prune process</doc> + <type name="RepoPruneFlags" c:type="OstreeRepoPruneFlags"/> + </parameter> + <parameter name="depth" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="386">Stop traversal after this many iterations (-1 for unlimited)</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="out_objects_total" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="387">Number of objects found</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="out_objects_pruned" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="388">Number of objects deleted</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="out_pruned_object_size_total" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="389">Storage size in bytes of objects deleted</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="390">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="prune_from_reachable" + c:identifier="ostree_repo_prune_from_reachable" + version="2017.1" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="477">Delete content from the repository. This function is the "backend" +half of the higher level ostree_repo_prune(). To use this function, +you determine the root set yourself, and this function finds all other +unreferenced objects and deletes them. + +Use this API when you want to perform more selective pruning - for example, +retain all commits from a production branch, but just GC some history from +your dev branch. + +The %OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE flag may be specified to just determine +statistics on objects that would be deleted, without actually deleting them. + +Locking: exclusive</doc> + <source-position filename="ostree-repo.h" line="1313"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="479">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="options" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="480">Options controlling prune process</doc> + <type name="RepoPruneOptions" c:type="OstreeRepoPruneOptions*"/> + </parameter> + <parameter name="out_objects_total" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="481">Number of objects found</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="out_objects_pruned" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="482">Number of objects deleted</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="out_pruned_object_size_total" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="483">Storage size in bytes of objects deleted</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="484">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="prune_static_deltas" + c:identifier="ostree_repo_prune_static_deltas" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="193">Prune static deltas, if COMMIT is specified then delete static delta files only +targeting that commit; otherwise any static delta of non existing commits are +deleted. + +Locking: exclusive</doc> + <source-position filename="ostree-repo.h" line="1276"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="195">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="commit" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="196">ASCII SHA256 checksum for commit, or %NULL for each +non existing commit</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="198">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="pull" c:identifier="ostree_repo_pull" throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5009">Connect to the remote repository, fetching the specified set of +refs @refs_to_fetch. For each ref that is changed, download the +commit, all metadata, and all content objects, storing them safely +on disk in @self. + +If @flags contains %OSTREE_REPO_PULL_FLAGS_MIRROR, and +the @refs_to_fetch is %NULL, and the remote repository contains a +summary file, then all refs will be fetched. + +If @flags contains %OSTREE_REPO_PULL_FLAGS_COMMIT_ONLY, then only the +metadata for the commits in @refs_to_fetch is pulled. + +Warning: This API will iterate the thread default main context, +which is a bug, but kept for compatibility reasons. If you want to +avoid this, use g_main_context_push_thread_default() to push a new +one around this call.</doc> + <source-position filename="ostree-repo.h" line="1340"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5011">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="remote_name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5012">Name of remote</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="refs_to_fetch" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5013">Optional list of refs; if %NULL, fetch all configured refs</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5014">Options controlling fetch behavior</doc> + <type name="RepoPullFlags" c:type="OstreeRepoPullFlags"/> + </parameter> + <parameter name="progress" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5015">Progress</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5016">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="pull_from_remotes_async" + c:identifier="ostree_repo_pull_from_remotes_async" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6274">Pull refs from multiple remotes which have been found using +ostree_repo_find_remotes_async(). + +@results are expected to be in priority order, with the best remotes to pull +from listed first. ostree_repo_pull_from_remotes_async() will generally pull +from the remotes in order, but may parallelise its downloads. + +If an error is encountered when pulling from a given remote, that remote will +be ignored and another will be tried instead. If any refs have not been +downloaded successfully after all remotes have been tried, %G_IO_ERROR_FAILED +will be returned. The results of any successful downloads will remain cached +in the local repository. + +If @cancellable is cancelled, %G_IO_ERROR_CANCELLED will be returned +immediately. The results of any successfully completed downloads at that +point will remain cached in the local repository. + +GPG verification of commits will be used unconditionally. + +The following @options are currently defined: + + * `flags` (`i`): #OstreeRepoPullFlags to apply to the pull operation + * `inherit-transaction` (`b`): %TRUE to inherit an ongoing transaction on + the #OstreeRepo, rather than encapsulating the pull in a new one + * `depth` (`i`): How far in the history to traverse; default is 0, -1 means infinite + * `disable-static-deltas` (`b`): Do not use static deltas + * `http-headers` (`a(ss)`): Additional headers to add to all HTTP requests + * `subdirs` (`as`): Pull just these subdirectories + * `update-frequency` (`u`): Frequency to call the async progress callback in + milliseconds, if any; only values higher than 0 are valid + * `append-user-agent` (`s`): Additional string to append to the user agent + * `n-network-retries` (`u`): Number of times to retry each download on receiving + a transient network error, such as a socket timeout; default is 5, 0 + means return errors without retrying. Since: 2018.6 + * `ref-keyring-map` (`a(sss)`): Array of (collection ID, ref name, keyring + remote name) tuples specifying which remote's keyring should be used when + doing GPG verification of each collection-ref. This is useful to prevent a + remote from serving malicious updates to refs which did not originate from + it. This can be a subset or superset of the refs being pulled; any ref + not being pulled will be ignored and any ref without a keyring remote + will be verified with the keyring of the remote being pulled from. + Since: 2019.2</doc> + <source-position filename="ostree-repo.h" line="1382"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6276">an #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="results" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6277">%NULL-terminated array of remotes to + pull from, including the refs to pull from each</doc> + <array c:type="const OstreeRepoFinderResult* const*"> + <type name="RepoFinderResult" c:type="OstreeRepoFinderResult*"/> + </array> + </parameter> + <parameter name="options" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6279">A GVariant `a{sv}` with an extensible set of flags</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="progress" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6280">an #OstreeAsyncProgress to update with the operation’s + progress, or %NULL</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6282">a #GCancellable, or %NULL</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" + transfer-ownership="none" + nullable="1" + allow-none="1" + scope="async" + closure="5"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6283">asynchronous completion callback</doc> + <type name="Gio.AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6284">data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="pull_from_remotes_finish" + c:identifier="ostree_repo_pull_from_remotes_finish" + version="2018.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6527">Finish an asynchronous pull operation started with +ostree_repo_pull_from_remotes_async().</doc> + <source-position filename="ostree-repo.h" line="1390"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6536">%TRUE on success, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6529">an #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6530">the asynchronous result</doc> + <type name="Gio.AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="pull_one_dir" + c:identifier="ostree_repo_pull_one_dir" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5048">This is similar to ostree_repo_pull(), but only fetches a single +subpath.</doc> + <source-position filename="ostree-repo.h" line="1350"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5050">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="remote_name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5051">Name of remote</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="dir_to_pull" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5052">Subdirectory path</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="refs_to_fetch" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5053">Optional list of refs; if %NULL, fetch all configured refs</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5054">Options controlling fetch behavior</doc> + <type name="RepoPullFlags" c:type="OstreeRepoPullFlags"/> + </parameter> + <parameter name="progress" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5055">Progress</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5056">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="pull_with_options" + c:identifier="ostree_repo_pull_with_options" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="3651">Like ostree_repo_pull(), but supports an extensible set of flags. +The following are currently defined: + + * `refs` (`as`): Array of string refs + * `collection-refs` (`a(sss)`): Array of (collection ID, ref name, checksum) tuples to pull; + mutually exclusive with `refs` and `override-commit-ids`. Checksums may be the empty + string to pull the latest commit for that ref + * `flags` (`i`): An instance of #OstreeRepoPullFlags + * `subdir` (`s`): Pull just this subdirectory + * `subdirs` (`as`): Pull just these subdirectories + * `override-remote-name` (`s`): If local, add this remote to refspec + * `gpg-verify` (`b`): GPG verify commits + * `gpg-verify-summary` (`b`): GPG verify summary + * `disable-sign-verify` (`b`): Disable signapi verification of commits + * `disable-sign-verify-summary` (`b`): Disable signapi verification of the summary + * `depth` (`i`): How far in the history to traverse; default is 0, -1 means infinite + * `per-object-fsync` (`b`): Perform disk writes more slowly, avoiding a single large I/O sync + * `disable-static-deltas` (`b`): Do not use static deltas + * `require-static-deltas` (`b`): Require static deltas + * `override-commit-ids` (`as`): Array of specific commit IDs to fetch for refs + * `timestamp-check` (`b`): Verify commit timestamps are newer than current (when pulling via ref); Since: 2017.11 + * `timestamp-check-from-rev` (`s`): Verify that all fetched commit timestamps are newer than timestamp of given rev; Since: 2020.4 + * `metadata-size-restriction` (`t`): Restrict metadata objects to a maximum number of bytes; 0 to disable. Since: 2018.9 + * `dry-run` (`b`): Only print information on what will be downloaded (requires static deltas) + * `override-url` (`s`): Fetch objects from this URL if remote specifies no metalink in options + * `inherit-transaction` (`b`): Don't initiate, finish or abort a transaction, useful to do multiple pulls in one transaction. + * `http-headers` (`a(ss)`): Additional headers to add to all HTTP requests + * `update-frequency` (`u`): Frequency to call the async progress callback in milliseconds, if any; only values higher than 0 are valid + * `localcache-repos` (`as`): File paths for local repos to use as caches when doing remote fetches + * `append-user-agent` (`s`): Additional string to append to the user agent + * `n-network-retries` (`u`): Number of times to retry each download on receiving + a transient network error, such as a socket timeout; default is 5, 0 + means return errors without retrying. Since: 2018.6 + * `ref-keyring-map` (`a(sss)`): Array of (collection ID, ref name, keyring + remote name) tuples specifying which remote's keyring should be used when + doing GPG verification of each collection-ref. This is useful to prevent a + remote from serving malicious updates to refs which did not originate from + it. This can be a subset or superset of the refs being pulled; any ref + not being pulled will be ignored and any ref without a keyring remote + will be verified with the keyring of the remote being pulled from. + Since: 2019.2 + * `summary-bytes` (`ay'): Contents of the `summary` file to use. If this is + specified, `summary-sig-bytes` must also be specified. This is + useful if doing multiple pull operations in a transaction, using + ostree_repo_remote_fetch_summary_with_options() beforehand to download + the `summary` and `summary.sig` once for the entire transaction. If not + specified, the `summary` will be downloaded from the remote. Since: 2020.5 + * `summary-sig-bytes` (`ay`): Contents of the `summary.sig` file. If this + is specified, `summary-bytes` must also be specified. Since: 2020.5 + * `disable-verify-bindings` (`b`): Disable verification of commit bindings. + Since: 2020.9</doc> + <source-position filename="ostree-repo.h" line="1360"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="3653">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="remote_name_or_baseurl" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="3654">Name of remote or file:// url</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="options" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="3655">A GVariant a{sv} with an extensible set of flags.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="progress" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="3656">Progress</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="3657">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="query_object_storage_size" + c:identifier="ostree_repo_query_object_storage_size" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4771">Return the size in bytes of object with checksum @sha256, after any +compression has been applied.</doc> + <source-position filename="ostree-repo.h" line="613"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4773">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4774">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="sha256" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4775">Checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_size" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4776">Size in bytes object occupies physically</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4777">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_commit" + c:identifier="ostree_repo_read_commit" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4974">Load the content for @rev into @out_root.</doc> + <source-position filename="ostree-repo.h" line="1034"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4976">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="ref" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4977">Ref or ASCII checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_root" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4978">An #OstreeRepoFile corresponding to the root</doc> + <type name="Gio.File" c:type="GFile**"/> + </parameter> + <parameter name="out_commit" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4979">The resolved commit checksum</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="4980">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="read_commit_detached_metadata" + c:identifier="ostree_repo_read_commit_detached_metadata" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3141">OSTree commits can have arbitrary metadata associated; this +function retrieves them. If none exists, @out_metadata will be set +to %NULL.</doc> + <source-position filename="ostree-repo.h" line="896"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3143">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3144">ASCII SHA256 commit checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_metadata" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3145">Metadata associated with commit in with format "a{sv}", or %NULL if none exists</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3146">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="regenerate_summary" + c:identifier="ostree_repo_regenerate_summary" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6135">An OSTree repository can contain a high level "summary" file that +describes the available branches and other metadata. + +If the timetable for making commits and updating the summary file is fairly +regular, setting the `ostree.summary.expires` key in @additional_metadata +will aid clients in working out when to check for updates. + +It is regenerated automatically after any ref is +added, removed, or updated if `core/auto-update-summary` is set. + +If the `core/collection-id` key is set in the configuration, it will be +included as %OSTREE_SUMMARY_COLLECTION_ID in the summary file. Refs that +have associated collection IDs will be included in the generated summary +file, listed under the %OSTREE_SUMMARY_COLLECTION_MAP key. Collection IDs +and refs in %OSTREE_SUMMARY_COLLECTION_MAP are guaranteed to be in +lexicographic order. + +Locking: shared (Prior to 2021.7, this was exclusive)</doc> + <source-position filename="ostree-repo.h" line="1582"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6137">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="additional_metadata" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6138">A GVariant of type a{sv}, or %NULL</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6139">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="reload_config" + c:identifier="ostree_repo_reload_config" + version="2017.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3501">By default, an #OstreeRepo will cache the remote configuration and its +own repo/config data. This API can be used to reload it.</doc> + <source-position filename="ostree-repo.h" line="146"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3503">repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3504">cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="remote_add" + c:identifier="ostree_repo_remote_add" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1820">Create a new remote named @name pointing to @url. If @options is +provided, then it will be mapped to #GKeyFile entries, where the +GVariant dictionary key is an option string, and the value is +mapped as follows: + * s: g_key_file_set_string() + * b: g_key_file_set_boolean() + * as: g_key_file_set_string_list()</doc> + <source-position filename="ostree-repo.h" line="151"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1822">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1823">Name of remote</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="url" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1824">URL for remote (if URL begins with metalink=, it will be used as such)</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="options" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1825">GVariant of type a{sv}</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1826">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="remote_change" + c:identifier="ostree_repo_remote_change" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2010">A combined function handling the equivalent of +ostree_repo_remote_add(), ostree_repo_remote_delete(), with more +options.</doc> + <source-position filename="ostree-repo.h" line="182"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2012">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="sysroot" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2013">System root</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="changeop" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2014">Operation to perform</doc> + <type name="RepoRemoteChange" c:type="OstreeRepoRemoteChange"/> + </parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2015">Name of remote</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="url" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2016">URL for remote (if URL begins with metalink=, it will be used as such)</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="options" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2017">GVariant of type a{sv}</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2018">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="remote_delete" + c:identifier="ostree_repo_remote_delete" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1906">Delete the remote named @name. It is an error if the provided +remote does not exist.</doc> + <source-position filename="ostree-repo.h" line="159"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1908">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1909">Name of remote</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1910">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="remote_fetch_summary" + c:identifier="ostree_repo_remote_fetch_summary" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2641">Tries to fetch the summary file and any GPG signatures on the summary file +over HTTP, and returns the binary data in @out_summary and @out_signatures +respectively. + +If no summary file exists on the remote server, @out_summary is set to +@NULL. Likewise if the summary file is not signed, @out_signatures is +set to @NULL. In either case the function still returns %TRUE. + +This method does not verify the signature of the downloaded summary file. +Use ostree_repo_verify_summary() for that. + +Parse the summary data into a #GVariant using g_variant_new_from_bytes() +with #OSTREE_SUMMARY_GVARIANT_FORMAT as the format string.</doc> + <source-position filename="ostree-repo.h" line="226"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2666">%TRUE on success, %FALSE on failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2643">Self</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2644">name of a remote</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_summary" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2645">return location for raw summary data, or + %NULL</doc> + <type name="GLib.Bytes" c:type="GBytes**"/> + </parameter> + <parameter name="out_signatures" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2647">return location for raw summary + signature data, or %NULL</doc> + <type name="GLib.Bytes" c:type="GBytes**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2649">a #GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="remote_fetch_summary_with_options" + c:identifier="ostree_repo_remote_fetch_summary_with_options" + version="2016.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6552">Like ostree_repo_remote_fetch_summary(), but supports an extensible set of flags. +The following are currently defined: + +- override-url (s): Fetch summary from this URL if remote specifies no metalink in options +- http-headers (a(ss)): Additional headers to add to all HTTP requests +- append-user-agent (s): Additional string to append to the user agent +- n-network-retries (u): Number of times to retry each download on receiving + a transient network error, such as a socket timeout; default is 5, 0 + means return errors without retrying</doc> + <source-position filename="ostree-repo.h" line="234"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6574">%TRUE on success, %FALSE on failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6554">Self</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6555">name of a remote</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="options" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6556">A GVariant a{sv} with an extensible set of flags</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="out_summary" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6557">return location for raw summary data, or + %NULL</doc> + <type name="GLib.Bytes" c:type="GBytes**"/> + </parameter> + <parameter name="out_signatures" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6559">return location for raw summary + signature data, or %NULL</doc> + <type name="GLib.Bytes" c:type="GBytes**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="6561">a #GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="remote_get_gpg_keys" + c:identifier="ostree_repo_remote_get_gpg_keys" + version="2021.4" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2513">Enumerate the trusted GPG keys for the remote @name. If @name is +%NULL, the global GPG keys will be returned. The keys will be +returned in the @out_keys #GPtrArray. Each element in the array is a +#GVariant of format %OSTREE_GPG_KEY_GVARIANT_FORMAT. The @key_ids +array can be used to limit which keys are included. If @key_ids is +%NULL, then all keys are included.</doc> + <source-position filename="ostree-repo.h" line="1484"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2532">%TRUE if the GPG keys could be enumerated, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2515">an #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="name" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2516">name of the remote or %NULL</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="key_ids" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2517"> + a %NULL-terminated array of GPG key IDs to include, or %NULL</doc> + <array c:type="const char* const*"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="out_keys" + direction="out" + caller-allocates="0" + transfer-ownership="container" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2519"> + return location for a #GPtrArray of the remote's trusted GPG keys, or + %NULL</doc> + <array name="GLib.PtrArray" c:type="GPtrArray**"> + <type name="GLib.Variant"/> + </array> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2522">a #GCancellable, or %NULL</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="remote_get_gpg_verify" + c:identifier="ostree_repo_remote_get_gpg_verify" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2171">Return whether GPG verification is enabled for the remote named @name +through @out_gpg_verify. It is an error if the provided remote does +not exist.</doc> + <source-position filename="ostree-repo.h" line="1439"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2182">%TRUE on success, %FALSE on failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2173">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2174">Name of remote</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_gpg_verify" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2175">Remote's GPG option</doc> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + </parameters> + </method> + <method name="remote_get_gpg_verify_summary" + c:identifier="ostree_repo_remote_get_gpg_verify_summary" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2205">Return whether GPG verification of the summary is enabled for the remote +named @name through @out_gpg_verify_summary. It is an error if the provided +remote does not exist.</doc> + <source-position filename="ostree-repo.h" line="1445"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2216">%TRUE on success, %FALSE on failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2207">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2208">Name of remote</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_gpg_verify_summary" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2209">Remote's GPG option</doc> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + </parameters> + </method> + <method name="remote_get_url" + c:identifier="ostree_repo_remote_get_url" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2128">Return the URL of the remote named @name through @out_url. It is an +error if the provided remote does not exist.</doc> + <source-position filename="ostree-repo.h" line="196"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2138">%TRUE on success, %FALSE on failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2130">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2131">Name of remote</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_url" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2132">Remote's URL</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="remote_gpg_import" + c:identifier="ostree_repo_remote_gpg_import" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2228">Imports one or more GPG keys from the open @source_stream, or from the +user's personal keyring if @source_stream is %NULL. The @key_ids array +can optionally restrict which keys are imported. If @key_ids is %NULL, +then all keys are imported. + +The imported keys will be used to conduct GPG verification when pulling +from the remote named @name.</doc> + <source-position filename="ostree-repo.h" line="1492"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2247">%TRUE on success, %FALSE on failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2230">Self</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2231">name of a remote</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="source_stream" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2232">a #GInputStream, or %NULL</doc> + <type name="Gio.InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="key_ids" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2233">a %NULL-terminated array of GPG key IDs, or %NULL</doc> + <array c:type="const char* const*"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="out_imported" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2234">return location for the number of imported + keys, or %NULL</doc> + <type name="guint" c:type="guint*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2236">a #GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="remote_list" c:identifier="ostree_repo_remote_list"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2077">List available remote names in an #OstreeRepo. Remote names are sorted +alphabetically. If no remotes are available the function returns %NULL.</doc> + <source-position filename="ostree-repo.h" line="192"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2085">a %NULL-terminated + array of remote names</doc> + <array length="0" zero-terminated="0" c:type="char**"> + <type name="utf8"/> + </array> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2079">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="out_n_remotes" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="2080">Number of remotes available</doc> + <type name="guint" c:type="guint*"/> + </parameter> + </parameters> + </method> + <method name="remote_list_collection_refs" + c:identifier="ostree_repo_remote_list_collection_refs" + version="2018.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="989">List refs advertised by @remote_name, including refs which are part of +collections. If the repository at @remote_name has a collection ID set, its +refs will be returned with that collection ID; otherwise, they will be returned +with a %NULL collection ID in each #OstreeCollectionRef key in @out_all_refs. +Any refs for other collections stored in the repository will also be returned. +No filtering is performed.</doc> + <source-position filename="ostree-repo.h" line="567"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="991">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="remote_name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="992">Name of the remote.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_all_refs" + direction="out" + caller-allocates="0" + transfer-ownership="container"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="993"> + Mapping from collection–ref to checksum</doc> + <type name="GLib.HashTable" c:type="GHashTable**"> + <type name="CollectionRef"/> + <type name="utf8"/> + </type> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="995">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="remote_list_refs" + c:identifier="ostree_repo_remote_list_refs" + throws="1"> + <source-position filename="ostree-repo.h" line="560"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="876">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="remote_name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="877">Name of the remote.</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_all_refs" + direction="out" + caller-allocates="0" + transfer-ownership="container"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="878"> + Mapping from ref to checksum</doc> + <type name="GLib.HashTable" c:type="GHashTable**"> + <type name="utf8"/> + <type name="utf8"/> + </type> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="880">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="resolve_collection_ref" + c:identifier="ostree_repo_resolve_collection_ref" + version="2018.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="496">Look up the checksum for the given collection–ref, returning it in @out_rev. +This will search through the mirrors and remote refs. + +If @allow_noent is %TRUE and the given @ref cannot be found, %TRUE will be +returned and @out_rev will be set to %NULL. If @allow_noent is %FALSE and +the given @ref cannot be found, a %G_IO_ERROR_NOT_FOUND error will be +returned. + +If you want to check only local refs, not remote or mirrored ones, use the +flag %OSTREE_REPO_RESOLVE_REV_EXT_LOCAL_ONLY. This is analogous to using +ostree_repo_resolve_rev_ext() but for collection-refs.</doc> + <source-position filename="ostree-repo.h" line="522"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="520">%TRUE on success, %FALSE on failure</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="498">an #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="ref" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="499">a collection–ref to resolve</doc> + <type name="CollectionRef" c:type="const OstreeCollectionRef*"/> + </parameter> + <parameter name="allow_noent" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="500">%TRUE to not throw an error if @ref doesn’t exist</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="501">options controlling behaviour</doc> + <type name="RepoResolveRevExtFlags" + c:type="OstreeRepoResolveRevExtFlags"/> + </parameter> + <parameter name="out_rev" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="502">return location for + the checksum corresponding to @ref, or %NULL if @allow_noent is %TRUE and + the @ref could not be found</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="505">a #GCancellable, or %NULL</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="resolve_keyring_for_collection" + c:identifier="ostree_repo_resolve_keyring_for_collection" + version="2018.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="1437">Find the GPG keyring for the given @collection_id, using the local +configuration from the given #OstreeRepo. This will search the configured +remotes for ones whose `collection-id` key matches @collection_id, and will +return the first matching remote. + +If multiple remotes match and have different keyrings, a debug message will +be emitted, and the first result will be returned. It is expected that the +keyrings should match. + +If no match can be found, a %G_IO_ERROR_NOT_FOUND error will be returned.</doc> + <source-position filename="ostree-repo.h" line="1395"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="1455">#OstreeRemote containing the GPG keyring for + @collection_id</doc> + <type name="Remote" c:type="OstreeRemote*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="1439">an #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="collection_id" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="1440">the collection ID to look up a keyring for</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull.c" + line="1441">a #GCancellable, or %NULL</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="resolve_rev" + c:identifier="ostree_repo_resolve_rev" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="444">Look up the given refspec, returning the checksum it references in +the parameter @out_rev. Will fall back on remote directory if cannot +find the given refspec in local.</doc> + <source-position filename="ostree-repo.h" line="497"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="446">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="refspec" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="447">A refspec</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="allow_noent" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="448">Do not throw an error if refspec does not exist</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="out_rev" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="449">A checksum,or %NULL if @allow_noent is true and it does not exist</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="resolve_rev_ext" + c:identifier="ostree_repo_resolve_rev_ext" + version="2016.7" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="466">Look up the given refspec, returning the checksum it references in +the parameter @out_rev. Differently from ostree_repo_resolve_rev(), +this will not fall back to searching through remote repos if a +local ref is specified but not found. + +The flag %OSTREE_REPO_RESOLVE_REV_EXT_LOCAL_ONLY is implied so +using it has no effect.</doc> + <source-position filename="ostree-repo.h" line="514"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="468">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="refspec" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="469">A refspec</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="allow_noent" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="470">Do not throw an error if refspec does not exist</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="471">Options controlling behavior</doc> + <type name="RepoResolveRevExtFlags" + c:type="OstreeRepoResolveRevExtFlags"/> + </parameter> + <parameter name="out_rev" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1"> + <doc xml:space="preserve" + filename="ostree-repo-refs.c" + line="472">A checksum,or %NULL if @allow_noent is true and it does not exist</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="scan_hardlinks" + c:identifier="ostree_repo_scan_hardlinks" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="1608">This function is deprecated in favor of using ostree_repo_devino_cache_new(), +which allows a precise mapping to be built up between hardlink checkout files +and their checksums between `ostree_repo_checkout_at()` and +`ostree_repo_write_directory_to_mtree()`. + +When invoking ostree_repo_write_directory_to_mtree(), it has to compute the +checksum of all files. If your commit contains hardlinks from a checkout, +this functions builds a mapping of device numbers and inodes to their +checksum. + +There is an upfront cost to creating this mapping, as this will scan the +entire objects directory. If your commit is composed of mostly hardlinks to +existing ostree objects, then this will speed up considerably, so call it +before you call ostree_repo_write_directory_to_mtree() or similar. However, +ostree_repo_devino_cache_new() is better as it avoids scanning all objects. + +Multithreading: This function is *not* MT safe.</doc> + <source-position filename="ostree-repo.h" line="310"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="1610">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="1611">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_alias_ref_immediate" + c:identifier="ostree_repo_set_alias_ref_immediate" + version="2017.10" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2221">Like ostree_repo_set_ref_immediate(), but creates an alias.</doc> + <source-position filename="ostree-repo.h" line="369"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2223">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="remote" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2224">A remote for the ref</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="ref" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2225">The ref to write</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="target" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2226">The ref target to point it to, or %NULL to unset</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2227">GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_cache_dir" + c:identifier="ostree_repo_set_cache_dir" + version="2016.5" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3662">Set a custom location for the cache directory used for e.g. +per-remote summary caches. Setting this manually is useful when +doing operations on a system repo as a user because you don't have +write permissions in the repo, where the cache is normally stored.</doc> + <source-position filename="ostree-repo.h" line="78"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3664">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="dfd" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3665">directory fd</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3666">subpath in @dfd</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3667">a #GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_collection_id" + c:identifier="ostree_repo_set_collection_id" + version="2018.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6619">Set or clear the collection ID of this repository. See [collection IDs][collection-ids]. +The update will be made in memory, but must be written out to the repository +configuration on disk using ostree_repo_write_config().</doc> + <source-position filename="ostree-repo.h" line="110"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6629">%TRUE on success, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6621">an #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="collection_id" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6622">new collection ID, or %NULL to unset it</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + <method name="set_collection_ref_immediate" + c:identifier="ostree_repo_set_collection_ref_immediate" + version="2018.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2247">This is like ostree_repo_transaction_set_collection_ref(), except it may be +invoked outside of a transaction. This is presently safe for the +case where we're creating or overwriting an existing ref.</doc> + <source-position filename="ostree-repo.h" line="377"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2259">%TRUE on success, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2249">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="ref" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2250">The collection–ref to write</doc> + <type name="CollectionRef" c:type="const OstreeCollectionRef*"/> + </parameter> + <parameter name="checksum" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2251">The checksum to point it to, or %NULL to unset</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2252">GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_disable_fsync" + c:identifier="ostree_repo_set_disable_fsync"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3645">Disable requests to fsync() to stable storage during commits. This +option should only be used by build system tools which are creating +disposable virtual machines, or have higher level mechanisms for +ensuring data consistency.</doc> + <source-position filename="ostree-repo.h" line="74"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3647">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="disable_fsync" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="3648">If %TRUE, do not fsync</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="set_ref_immediate" + c:identifier="ostree_repo_set_ref_immediate" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2193">This is like ostree_repo_transaction_set_ref(), except it may be +invoked outside of a transaction. This is presently safe for the +case where we're creating or overwriting an existing ref. + +Multithreading: This function is MT safe.</doc> + <source-position filename="ostree-repo.h" line="361"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2195">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="remote" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2196">A remote for the ref</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="ref" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2197">The ref to write</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="checksum" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2198">The checksum to point it to, or %NULL to unset</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2199">GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="sign_commit" + c:identifier="ostree_repo_sign_commit" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5376">Add a GPG signature to a commit.</doc> + <source-position filename="ostree-repo.h" line="1413"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5378">Self</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="commit_checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5379">SHA256 of given commit to sign</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key_id" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5380">Use this GPG key id</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="homedir" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5381">GPG home directory, or %NULL</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5382">A #GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="sign_delta" + c:identifier="ostree_repo_sign_delta" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5465">This function is deprecated, sign the summary file instead. +Add a GPG signature to a static delta.</doc> + <source-position filename="ostree-repo.h" line="1421"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5467">Self</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="from_commit" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5468">From commit</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="to_commit" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5469">To commit</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="key_id" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5470">key id</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="homedir" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5471">homedir</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5472">cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="signature_verify_commit_data" + c:identifier="ostree_repo_signature_verify_commit_data" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull-verify.c" + line="357">Validate the commit data using the commit metadata which must +contain at least one valid signature. If GPG and signapi are +both enabled, then both must find at least one valid signature.</doc> + <source-position filename="ostree-repo.h" line="1573"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull-verify.c" + line="359">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="remote_name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull-verify.c" + line="360">Name of remote</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="commit_data" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull-verify.c" + line="361">Commit object data (GVariant)</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="commit_metadata" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull-verify.c" + line="362">Commit metadata (GVariant `a{sv}`), must contain at least one valid signature</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-pull-verify.c" + line="363">Optionally disable GPG or signapi</doc> + <type name="RepoVerifyFlags" c:type="OstreeRepoVerifyFlags"/> + </parameter> + <parameter name="out_results" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1"> + <doc xml:space="preserve" + filename="ostree-repo-pull-verify.c" + line="364">Textual description of results</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="static_delta_execute_offline" + c:identifier="ostree_repo_static_delta_execute_offline" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="634">Given a directory representing an already-downloaded static delta +on disk, apply it, generating a new commit. The directory must be +named with the form "FROM-TO", where both are checksums, and it +must contain a file named "superblock", along with at least one part.</doc> + <source-position filename="ostree-repo.h" line="1147"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="636">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="dir_or_file" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="637">Path to a directory containing static delta data, or directly to the superblock</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="skip_validation" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="638">If %TRUE, assume data integrity</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="639">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="static_delta_execute_offline_with_signature" + c:identifier="ostree_repo_static_delta_execute_offline_with_signature" + version="2020.7" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="388">Given a directory representing an already-downloaded static delta +on disk, apply it, generating a new commit. +If sign is passed, the static delta signature is verified. +If sign-verify-deltas configuration option is set and static delta is signed, +signature verification will be mandatory before apply the static delta. +The directory must be named with the form "FROM-TO", where both are +checksums, and it must contain a file named "superblock", along with at least +one part.</doc> + <source-position filename="ostree-repo.h" line="1139"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="390">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="dir_or_file" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="391">Path to a directory containing static delta data, or directly to the superblock</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="sign" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="392">Signature engine used to check superblock</doc> + <type name="Sign" c:type="OstreeSign*"/> + </parameter> + <parameter name="skip_validation" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="393">If %TRUE, assume data integrity</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="394">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="static_delta_generate" + c:identifier="ostree_repo_static_delta_generate" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-compilation.c" + line="1310">Generate a lookaside "static delta" from @from (%NULL means +from-empty) which can generate the objects in @to. This delta is +an optimization over fetching individual objects, and can be +conveniently stored and applied offline. + +The @params argument should be an a{sv}. The following attributes +are known: + - min-fallback-size: u: Minimum uncompressed size in megabytes to use fallback, 0 to disable fallbacks + - max-chunk-size: u: Maximum size in megabytes of a delta part + - max-bsdiff-size: u: Maximum size in megabytes to consider bsdiff compression + for input files + - compression: y: Compression type: 0=none, x=lzma, g=gzip + - bsdiff-enabled: b: Enable bsdiff compression. Default TRUE. + - inline-parts: b: Put part data in header, to get a single file delta. Default FALSE. + - verbose: b: Print diagnostic messages. Default FALSE. + - endianness: b: Deltas use host byte order by default; this option allows choosing (G_BIG_ENDIAN or G_LITTLE_ENDIAN) + - filename: ay: Save delta superblock to this filename, and parts in the same directory. Default saves to repository. + - sign-name: ay: Signature type to use. + - sign-key-ids: as: Array of keys used to sign delta superblock.</doc> + <source-position filename="ostree-repo.h" line="1102"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-compilation.c" + line="1312">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="opt" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-compilation.c" + line="1313">High level optimization choice</doc> + <type name="StaticDeltaGenerateOpt" + c:type="OstreeStaticDeltaGenerateOpt"/> + </parameter> + <parameter name="from" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-compilation.c" + line="1314">ASCII SHA256 checksum of origin, or %NULL</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="to" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-compilation.c" + line="1315">ASCII SHA256 checksum of target</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="metadata" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-compilation.c" + line="1316">Optional metadata</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="params" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-compilation.c" + line="1317">Parameters, see below</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-compilation.c" + line="1318">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="static_delta_reindex" + c:identifier="ostree_repo_static_delta_reindex" + version="2020.8" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="1245">The delta index for a particular commit lists all the existing deltas that can be used +when downloading that commit. This operation regenerates these indexes, either for +a particular commit (if @opt_to_commit is non-%NULL), or for all commits that +are reachable by an existing delta (if @opt_to_commit is %NULL). + +This is normally called automatically when the summary is updated in ostree_repo_regenerate_summary(). + +Locking: shared</doc> + <source-position filename="ostree-repo.h" line="1132"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="1247">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="1248">Flags affecting the indexing operation</doc> + <type name="StaticDeltaIndexFlags" + c:type="OstreeStaticDeltaIndexFlags"/> + </parameter> + <parameter name="opt_to_commit" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="1249">ASCII SHA256 checksum of target commit, or %NULL to index all targets</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="1250">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="static_delta_verify_signature" + c:identifier="ostree_repo_static_delta_verify_signature" + version="2020.7" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="1165">Verify static delta file signature.</doc> + <source-position filename="ostree-repo.h" line="1154"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="1175">TRUE if the signature of static delta file is valid using the +signature engine provided, FALSE otherwise.</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="1167">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="delta_id" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="1168">delta path</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="sign" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="1169">Signature engine used to check superblock</doc> + <type name="Sign" c:type="OstreeSign*"/> + </parameter> + <parameter name="out_success_message" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-static-delta-core.c" + line="1170">success message</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="transaction_set_collection_ref" + c:identifier="ostree_repo_transaction_set_collection_ref" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2151">If @checksum is not %NULL, then record it as the target of local ref named +@ref. + +Otherwise, if @checksum is %NULL, then record that the ref should +be deleted. + +The change will not be written out immediately, but when the transaction +is completed with ostree_repo_commit_transaction(). If the transaction +is instead aborted with ostree_repo_abort_transaction(), no changes will +be made to the repository. + +Multithreading: Since v2017.15 this function is MT safe.</doc> + <source-position filename="ostree-repo.h" line="356"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2153">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="ref" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2154">The collection–ref to write</doc> + <type name="CollectionRef" c:type="const OstreeCollectionRef*"/> + </parameter> + <parameter name="checksum" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2155">The checksum to point it to</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="transaction_set_ref" + c:identifier="ostree_repo_transaction_set_ref"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2100">If @checksum is not %NULL, then record it as the target of ref named +@ref; if @remote is provided, the ref will appear to originate from that +remote. + +Otherwise, if @checksum is %NULL, then record that the ref should +be deleted. + +The change will be written when the transaction is completed with +ostree_repo_commit_transaction(); that function takes care of writing all of +the objects (such as the commit referred to by @checksum) before updating the +refs. If the transaction is instead aborted with +ostree_repo_abort_transaction(), no changes to the ref will be made to the +repository. + +Note however that currently writing *multiple* refs is not truly atomic; if +the process or system is terminated during +ostree_repo_commit_transaction(), it is possible that just some of the refs +will have been updated. Your application should take care to handle this +case. + +Multithreading: Since v2017.15 this function is MT safe.</doc> + <source-position filename="ostree-repo.h" line="350"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2102">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="remote" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2103">A remote for the ref</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="ref" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2104">The ref to write</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="checksum" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2105">The checksum to point it to</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="transaction_set_refspec" + c:identifier="ostree_repo_transaction_set_refspec"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2073">Like ostree_repo_transaction_set_ref(), but takes concatenated +@refspec format as input instead of separate remote and name +arguments. + +Multithreading: Since v2017.15 this function is MT safe.</doc> + <source-position filename="ostree-repo.h" line="345"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2075">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="refspec" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2076">The refspec to write</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="checksum" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2077">The checksum to point it to</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="traverse_commit" + c:identifier="ostree_repo_traverse_commit" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="703">Create a new set @out_reachable containing all objects reachable +from @commit_checksum, traversing @maxdepth parent commits.</doc> + <source-position filename="ostree-repo.h" line="1170"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="705">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="commit_checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="706">ASCII SHA256 checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="maxdepth" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="707">Traverse this many parent commits, -1 for unlimited</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="out_reachable" + direction="out" + caller-allocates="0" + transfer-ownership="container"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="708">Set of reachable objects</doc> + <type name="GLib.HashTable" c:type="GHashTable**"> + <type name="GLib.Variant"/> + <type name="GLib.Variant"/> + </type> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="709">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="traverse_commit_union" + c:identifier="ostree_repo_traverse_commit_union" + introspectable="0" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="677">Update the set @inout_reachable containing all objects reachable +from @commit_checksum, traversing @maxdepth parent commits.</doc> + <source-position filename="ostree-repo.h" line="1178"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="679">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="commit_checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="680">ASCII SHA256 checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="maxdepth" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="681">Traverse this many parent commits, -1 for unlimited</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="inout_reachable" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="682">Set of reachable objects</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="683">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="traverse_commit_union_with_parents" + c:identifier="ostree_repo_traverse_commit_union_with_parents" + version="2018.5" + introspectable="0" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="644">Update the set @inout_reachable containing all objects reachable +from @commit_checksum, traversing @maxdepth parent commits. + +Additionally this constructs a mapping from each object to the parents +of the object, which can be used to track which commits an object +belongs to.</doc> + <source-position filename="ostree-repo.h" line="1186"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="646">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="commit_checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="647">ASCII SHA256 checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="maxdepth" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="648">Traverse this many parent commits, -1 for unlimited</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="inout_reachable" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="649">Set of reachable objects</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="inout_parents" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="650">Map from object to parent object</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="651">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="traverse_commit_with_flags" + c:identifier="ostree_repo_traverse_commit_with_flags" + version="2018.5" + introspectable="0" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="544">Update the set @inout_reachable containing all objects reachable +from @commit_checksum, traversing @maxdepth parent commits. + +Additionally this constructs a mapping from each object to the parents +of the object, which can be used to track which commits an object +belongs to.</doc> + <source-position filename="ostree-repo.h" line="1195"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="546">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="547">change traversal behaviour according to these flags</doc> + <type name="RepoCommitTraverseFlags" + c:type="OstreeRepoCommitTraverseFlags"/> + </parameter> + <parameter name="commit_checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="548">ASCII SHA256 checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="maxdepth" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="549">Traverse this many parent commits, -1 for unlimited</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="inout_reachable" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="550">Set of reachable objects</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="inout_parents" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="551">Map from object to parent object</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="552">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="traverse_reachable_refs" + c:identifier="ostree_repo_traverse_reachable_refs" + version="2018.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="356">Add all commit objects directly reachable via a ref to @reachable. + +Locking: shared</doc> + <source-position filename="ostree-repo.h" line="1306"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="358">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="depth" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="359">Depth of traversal</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="reachable" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="360">Set of reachable objects (will be modified)</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="GLib.Variant"/> + <type name="GLib.Variant"/> + </type> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-prune.c" + line="361">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="verify_commit" + c:identifier="ostree_repo_verify_commit" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5878">Check for a valid GPG signature on commit named by the ASCII +checksum @commit_checksum.</doc> + <source-position filename="ostree-repo.h" line="1431"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5890">%TRUE if there was a GPG signature from a trusted keyring, otherwise %FALSE</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5880">Repository</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="commit_checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5881">ASCII SHA256 checksum</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="keyringdir" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5882">Path to directory GPG keyrings; overrides built-in default if given</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="extra_keyring" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5883">Path to additional keyring file (not a directory)</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5884">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="verify_commit_ext" + c:identifier="ostree_repo_verify_commit_ext" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5916">Read GPG signature(s) on the commit named by the ASCII checksum +@commit_checksum and return detailed results.</doc> + <source-position filename="ostree-repo.h" line="1525"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5928">an #OstreeGpgVerifyResult, or %NULL on error</doc> + <type name="GpgVerifyResult" c:type="OstreeGpgVerifyResult*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5918">Repository</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="commit_checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5919">ASCII SHA256 checksum</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="keyringdir" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5920">Path to directory GPG keyrings; overrides built-in default if given</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="extra_keyring" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5921">Path to additional keyring file (not a directory)</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5922">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="verify_commit_for_remote" + c:identifier="ostree_repo_verify_commit_for_remote" + version="2016.14" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5952">Read GPG signature(s) on the commit named by the ASCII checksum +@commit_checksum and return detailed results, based on the keyring +configured for @remote.</doc> + <source-position filename="ostree-repo.h" line="1534"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5964">an #OstreeGpgVerifyResult, or %NULL on error</doc> + <type name="GpgVerifyResult" c:type="OstreeGpgVerifyResult*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5954">Repository</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="commit_checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5955">ASCII SHA256 checksum</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="remote_name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5956">OSTree remote to use for configuration</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="5957">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="verify_summary" + c:identifier="ostree_repo_verify_summary" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6039">Verify @signatures for @summary data using GPG keys in the keyring for +@remote_name, and return an #OstreeGpgVerifyResult.</doc> + <source-position filename="ostree-repo.h" line="1551"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6051">an #OstreeGpgVerifyResult, or %NULL on error</doc> + <type name="GpgVerifyResult" c:type="OstreeGpgVerifyResult*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6041">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="remote_name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6042">Name of remote</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="summary" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6043">Summary data as a #GBytes</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="signatures" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6044">Summary signatures as a #GBytes</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="6045">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_archive_to_mtree" + c:identifier="ostree_repo_write_archive_to_mtree" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="971">Import an archive file @archive into the repository, and write its +file structure to @mtree.</doc> + <source-position filename="ostree-repo.h" line="764"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="973">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="archive" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="974">A path to an archive file</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="mtree" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="975">The #OstreeMutableTree to write to</doc> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </parameter> + <parameter name="modifier" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="976">Optional commit modifier</doc> + <type name="RepoCommitModifier" + c:type="OstreeRepoCommitModifier*"/> + </parameter> + <parameter name="autocreate_parents" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="977">Autocreate parent directories</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="978">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_archive_to_mtree_from_fd" + c:identifier="ostree_repo_write_archive_to_mtree_from_fd" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="1006">Read an archive from @fd and import it into the repository, writing +its file structure to @mtree.</doc> + <source-position filename="ostree-repo.h" line="774"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="1008">An #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="1009">A file descriptor to read the archive from</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="mtree" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="1010">The #OstreeMutableTree to write to</doc> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </parameter> + <parameter name="modifier" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="1011">Optional commit modifier</doc> + <type name="RepoCommitModifier" + c:type="OstreeRepoCommitModifier*"/> + </parameter> + <parameter name="autocreate_parents" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="1012">Autocreate parent directories</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-libarchive.c" + line="1013">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_commit" + c:identifier="ostree_repo_write_commit" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3034">Write a commit metadata object, referencing @root_contents_checksum +and @root_metadata_checksum. +This uses the current time as the commit timestamp, but it can be +overridden with an explicit timestamp via the +[standard](https://reproducible-builds.org/specs/source-date-epoch/) +`SOURCE_DATE_EPOCH` environment flag.</doc> + <source-position filename="ostree-repo.h" line="873"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3036">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="parent" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3037">ASCII SHA256 checksum for parent, or %NULL for none</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="subject" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3038">Subject</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="body" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3039">Body</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="metadata" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3040">GVariant of type a{sv}, or %NULL for none</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="root" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3041">The tree to point the commit to</doc> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </parameter> + <parameter name="out_commit" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3042">Resulting ASCII SHA256 checksum for commit</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3043">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_commit_detached_metadata" + c:identifier="ostree_repo_write_commit_detached_metadata" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3191">Replace any existing metadata associated with commit referred to by +@checksum with @metadata. If @metadata is %NULL, then existing +data will be deleted.</doc> + <source-position filename="ostree-repo.h" line="903"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3193">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3194">ASCII SHA256 commit checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="metadata" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3195">Metadata to associate with commit in with format "a{sv}", or %NULL to delete</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3196">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_commit_with_time" + c:identifier="ostree_repo_write_commit_with_time" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3087">Write a commit metadata object, referencing @root_contents_checksum +and @root_metadata_checksum.</doc> + <source-position filename="ostree-repo.h" line="884"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3089">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="parent" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3090">ASCII SHA256 checksum for parent, or %NULL for none</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="subject" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3091">Subject</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="body" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3092">Body</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="metadata" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3093">GVariant of type a{sv}, or %NULL for none</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="root" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3094">The tree to point the commit to</doc> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </parameter> + <parameter name="time" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3095">The time to use to stamp the commit</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="out_commit" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3096">Resulting ASCII SHA256 checksum for commit</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3097">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_config" + c:identifier="ostree_repo_write_config" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1630">Save @new_config in place of this repository's config file.</doc> + <source-position filename="ostree-repo.h" line="246"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1632">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="new_config" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1633">Overwrite the config file with this data</doc> + <type name="GLib.KeyFile" c:type="GKeyFile*"/> + </parameter> + </parameters> + </method> + <method name="write_content" + c:identifier="ostree_repo_write_content" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2739">Store the content object streamed as @object_input, +with total length @length. The actual checksum will +be returned as @out_csum.</doc> + <source-position filename="ostree-repo.h" line="416"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2741">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="expected_checksum" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2742">If provided, validate content against this checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="object_input" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2743">Content object stream</doc> + <type name="Gio.InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2744">Length of @object_input</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="out_csum" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2745">Binary checksum</doc> + <array zero-terminated="0" c:type="guchar**" fixed-size="32"> + <type name="guint8" c:type="guchar*"/> + </array> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2746">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_content_async" + c:identifier="ostree_repo_write_content_async"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2957">Asynchronously store the content object @object. If provided, the +checksum @expected_checksum will be verified.</doc> + <source-position filename="ostree-repo.h" line="482"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2959">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="expected_checksum" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2960">If provided, validate content against this checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2961">Input</doc> + <type name="Gio.InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2962">Length of @object</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2963">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" + transfer-ownership="none" + nullable="1" + allow-none="1" + scope="async" + closure="5"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2964">Invoked when content is writed</doc> + <type name="Gio.AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2965">User data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="write_content_finish" + c:identifier="ostree_repo_write_content_finish" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2998">Completes an invocation of ostree_repo_write_content_async().</doc> + <source-position filename="ostree-repo.h" line="491"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3000">a #OstreeRepo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3001">a #GAsyncResult</doc> + <type name="Gio.AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="out_csum" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="3002">A binary SHA256 checksum of the content object</doc> + <type name="guint8" c:type="guchar**"/> + </parameter> + </parameters> + </method> + <method name="write_content_trusted" + c:identifier="ostree_repo_write_content_trusted" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2712">Store the content object streamed as @object_input, with total +length @length. The given @checksum will be treated as trusted. + +This function should be used when importing file objects from local +disk, for example.</doc> + <source-position filename="ostree-repo.h" line="474"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2714">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2715">Store content using this ASCII SHA256 checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="object_input" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2716">Content stream</doc> + <type name="Gio.InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2717">Length of @object_input</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2718">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_dfd_to_mtree" + c:identifier="ostree_repo_write_dfd_to_mtree" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4160">Store as objects all contents of the directory referred to by @dfd +and @path all children into the repository @self, overlaying the +resulting filesystem hierarchy into @mtree.</doc> + <source-position filename="ostree-repo.h" line="754"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4162">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="dfd" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4163">Directory file descriptor</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4164">Path</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="mtree" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4165">Overlay directory contents into this tree</doc> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </parameter> + <parameter name="modifier" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4166">Optional modifier</doc> + <type name="RepoCommitModifier" + c:type="OstreeRepoCommitModifier*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4167">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_directory_to_mtree" + c:identifier="ostree_repo_write_directory_to_mtree" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4119">Store objects for @dir and all children into the repository @self, +overlaying the resulting filesystem hierarchy into @mtree.</doc> + <source-position filename="ostree-repo.h" line="746"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4121">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="dir" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4122">Path to a directory</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="mtree" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4123">Overlay directory contents into this tree</doc> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </parameter> + <parameter name="modifier" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4124">Optional modifier</doc> + <type name="RepoCommitModifier" + c:type="OstreeRepoCommitModifier*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4125">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_metadata" + c:identifier="ostree_repo_write_metadata" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2446">Store the metadata object @object. Return the checksum +as @out_csum. + +If @expected_checksum is not %NULL, verify it against the +computed checksum.</doc> + <source-position filename="ostree-repo.h" line="392"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2448">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2449">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="expected_checksum" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2450">If provided, validate content against this checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2451">Metadata</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="out_csum" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2452">Binary checksum</doc> + <array zero-terminated="0" c:type="guchar**" fixed-size="32"> + <type name="guint8" c:type="guchar*"/> + </array> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2453">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_metadata_async" + c:identifier="ostree_repo_write_metadata_async"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2621">Asynchronously store the metadata object @variant. If provided, +the checksum @expected_checksum will be verified.</doc> + <source-position filename="ostree-repo.h" line="401"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2623">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2624">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="expected_checksum" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2625">If provided, validate content against this checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="object" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2626">Metadata</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2627">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" + transfer-ownership="none" + nullable="1" + allow-none="1" + scope="async" + closure="5"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2628">Invoked when metadata is writed</doc> + <type name="Gio.AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2629">Data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="write_metadata_finish" + c:identifier="ostree_repo_write_metadata_finish" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2662">Complete a call to ostree_repo_write_metadata_async().</doc> + <source-position filename="ostree-repo.h" line="410"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2664">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2665">Result</doc> + <type name="Gio.AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="out_csum" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2666">Binary checksum value</doc> + <array zero-terminated="0" c:type="guchar**" fixed-size="32"> + <type name="guint8"/> + </array> + </parameter> + </parameters> + </method> + <method name="write_metadata_stream_trusted" + c:identifier="ostree_repo_write_metadata_stream_trusted" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2519">Store the metadata object @variant; the provided @checksum is +trusted.</doc> + <source-position filename="ostree-repo.h" line="465"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2521">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2522">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2523">Store object with this ASCII SHA256 checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="object_input" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2524">Metadata object stream</doc> + <type name="Gio.InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="length" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2525">Length, may be 0 for unknown</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2526">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_metadata_trusted" + c:identifier="ostree_repo_write_metadata_trusted" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2556">Store the metadata object @variant; the provided @checksum is +trusted.</doc> + <source-position filename="ostree-repo.h" line="457"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2558">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2559">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2560">Store object with this ASCII SHA256 checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="variant" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2561">Metadata object</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2562">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_mtree" + c:identifier="ostree_repo_write_mtree" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4210">Write all metadata objects for @mtree to repo; the resulting +@out_file points to the %OSTREE_OBJECT_TYPE_DIR_TREE object that +the @mtree represented.</doc> + <source-position filename="ostree-repo.h" line="866"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4212">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="mtree" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4213">Mutable tree</doc> + <type name="MutableTree" c:type="OstreeMutableTree*"/> + </parameter> + <parameter name="out_file" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4214">An #OstreeRepoFile representing @mtree's root.</doc> + <type name="Gio.File" c:type="GFile**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4215">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_regfile" + c:identifier="ostree_repo_write_regfile" + version="2021.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2884">Create an `OstreeContentWriter` that allows streaming output into +the repository.</doc> + <source-position filename="ostree-repo.h" line="437"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2898">A new writer, or %NULL on error</doc> + <type name="ContentWriter" c:type="OstreeContentWriter*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2886">Repo,</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="expected_checksum" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2887">Expected checksum (SHA-256 hex string)</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="uid" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2888">user id</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + <parameter name="gid" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2889">group id</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2890">Unix file mode</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + <parameter name="content_len" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2891">Expected content length</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="xattrs" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2892">Extended attributes (GVariant type `(ayay)`)</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="write_regfile_inline" + c:identifier="ostree_repo_write_regfile_inline" + version="2021.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2797">Synchronously create a file object from the provided content. This API +is intended for small files where it is reasonable to buffer the entire +content in memory. + +Unlike `ostree_repo_write_content()`, if @expected_checksum is provided, +this function will not check for the presence of the object beforehand.</doc> + <source-position filename="ostree-repo.h" line="425"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2816">Checksum (as a hex string) of the committed file</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2799">repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="expected_checksum" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2800">The expected checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="uid" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2801">User id</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + <parameter name="gid" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2802">Group id</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2803">File mode</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + <parameter name="xattrs" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2804">Extended attributes, GVariant of type (ayay)</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="buf" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2805">File contents</doc> + <array length="6" zero-terminated="0" c:type="const guint8*"> + <type name="guint8"/> + </array> + </parameter> + <parameter name="len" transfer-ownership="none"> + <type name="gsize" c:type="gsize"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2806">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_symlink" + c:identifier="ostree_repo_write_symlink" + version="2021.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2843">Synchronously create a symlink object. + +Unlike `ostree_repo_write_content()`, if @expected_checksum is provided, +this function will not check for the presence of the object beforehand.</doc> + <source-position filename="ostree-repo.h" line="447"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2859">Checksum (as a hex string) of the committed file</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2845">repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </instance-parameter> + <parameter name="expected_checksum" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2846">The expected checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="uid" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2847">User id</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + <parameter name="gid" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2848">Group id</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + <parameter name="xattrs" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2849">Extended attributes, GVariant of type (ayay)</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="symlink_target" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2850">Target of the symbolic link</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="2851">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <property name="path" + writable="1" + construct-only="1" + transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1286">Path to repository. Note that if this repository was created +via `ostree_repo_new_at()`, this value will refer to a value in +the Linux kernel's `/proc/self/fd` directory. Generally, you +should avoid using this property at all; you can gain a reference +to the repository's directory fd via `ostree_repo_get_dfd()` and +use file-descriptor relative operations.</doc> + <type name="Gio.File"/> + </property> + <property name="remotes-config-dir" + writable="1" + construct-only="1" + transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1319">Path to directory containing remote definitions. The default is `NULL`. +If a `sysroot-path` property is defined, this value will default to +`${sysroot_path}/etc/ostree/remotes.d`. + +This value will only be used for system repositories.</doc> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="sysroot-path" + writable="1" + construct-only="1" + transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1301">A system using libostree for the host has a "system" repository; this +property will be set for repositories referenced via +`ostree_sysroot_repo()` for example. + +You should avoid using this property; if your code is operating +on a system repository, use `OstreeSysroot` and access the repository +object via `ostree_sysroot_repo()`.</doc> + <type name="Gio.File"/> + </property> + <glib:signal name="gpg-verify-result" when="last"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1337">Emitted during a pull operation upon GPG verification (if enabled). +Applications can connect to this signal to output the verification +results if desired. + +The signal will be emitted from whichever #GMainContext is the +thread-default at the point when ostree_repo_pull_with_options() +is called.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1340">checksum of the signed object</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="1341">an #OstreeGpgVerifyResult</doc> + <type name="GpgVerifyResult"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="RepoCheckoutAtOptions" c:type="OstreeRepoCheckoutAtOptions"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="972">An extensible options structure controlling checkout. Ensure that +you have entirely zeroed the structure, then set just the desired +options. This is used by ostree_repo_checkout_at() which +supercedes previous separate enumeration usage in +ostree_repo_checkout_tree() and ostree_repo_checkout_tree_at().</doc> + <source-position filename="ostree-repo.h" line="1005"/> + <field name="mode" writable="1"> + <type name="RepoCheckoutMode" c:type="OstreeRepoCheckoutMode"/> + </field> + <field name="overwrite_mode" writable="1"> + <type name="RepoCheckoutOverwriteMode" + c:type="OstreeRepoCheckoutOverwriteMode"/> + </field> + <field name="enable_uncompressed_cache" writable="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="enable_fsync" writable="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="process_whiteouts" writable="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="no_copy_fallback" writable="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="force_copy" writable="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="bareuseronly_dirs" writable="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="force_copy_zerosized" writable="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="unused_bools" writable="1"> + <array zero-terminated="0" fixed-size="4"> + <type name="gboolean" c:type="gboolean"/> + </array> + </field> + <field name="subpath" writable="1"> + <type name="utf8" c:type="const char*"/> + </field> + <field name="devino_to_csum_cache" writable="1"> + <type name="RepoDevInoCache" c:type="OstreeRepoDevInoCache*"/> + </field> + <field name="unused_ints" writable="1"> + <array zero-terminated="0" fixed-size="6"> + <type name="gint" c:type="int"/> + </array> + </field> + <field name="unused_ptrs" writable="1"> + <array zero-terminated="0" fixed-size="3"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + <field name="filter" writable="1"> + <type name="RepoCheckoutFilter" c:type="OstreeRepoCheckoutFilter"/> + </field> + <field name="filter_user_data" writable="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="sepolicy" writable="1"> + <type name="SePolicy" c:type="OstreeSePolicy*"/> + </field> + <field name="sepolicy_prefix" writable="1"> + <type name="utf8" c:type="const char*"/> + </field> + <method name="set_devino" + c:identifier="ostree_repo_checkout_at_options_set_devino" + version="2017.13"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1410">This function simply assigns @cache to the `devino_to_csum_cache` member of +@opts; it's only useful for introspection. + +Note that cache does *not* have its refcount incremented - the lifetime of +@cache must be equal to or greater than that of @opts.</doc> + <source-position filename="ostree-repo.h" line="1017"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="opts" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1412">Checkout options</doc> + <type name="RepoCheckoutAtOptions" + c:type="OstreeRepoCheckoutAtOptions*"/> + </instance-parameter> + <parameter name="cache" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1413">Devino cache</doc> + <type name="RepoDevInoCache" c:type="OstreeRepoDevInoCache*"/> + </parameter> + </parameters> + </method> + </record> + <callback name="RepoCheckoutFilter" + c:type="OstreeRepoCheckoutFilter" + version="2018.2"> + <source-position filename="ostree-repo.h" line="967"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="963">#OstreeRepoCheckoutFilterResult saying whether or not to checkout this file</doc> + <type name="RepoCheckoutFilterResult" + c:type="OstreeRepoCheckoutFilterResult"/> + </return-value> + <parameters> + <parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="958">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="959">Path to file</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="stbuf" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="960">File information</doc> + <type name="gpointer" c:type="stat*"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1" + closure="3"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="961">User data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <enumeration name="RepoCheckoutFilterResult" + version="2018.2" + c:type="OstreeRepoCheckoutFilterResult"> + <source-position filename="ostree-repo.h" line="954"/> + <member name="allow" + value="0" + c:identifier="OSTREE_REPO_CHECKOUT_FILTER_ALLOW"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="946">Do checkout this object</doc> + </member> + <member name="skip" + value="1" + c:identifier="OSTREE_REPO_CHECKOUT_FILTER_SKIP"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="947">Ignore this object</doc> + </member> + </enumeration> + <enumeration name="RepoCheckoutMode" c:type="OstreeRepoCheckoutMode"> + <source-position filename="ostree-repo.h" line="917"/> + <member name="none" + value="0" + c:identifier="OSTREE_REPO_CHECKOUT_MODE_NONE"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="911">No special options</doc> + </member> + <member name="user" + value="1" + c:identifier="OSTREE_REPO_CHECKOUT_MODE_USER"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="912">Ignore uid/gid of files</doc> + </member> + </enumeration> + <record name="RepoCheckoutOptions" + c:type="OstreeRepoCheckoutOptions" + introspectable="0"> + <doc xml:space="preserve" + filename="ostree-repo-deprecated.h" + line="33">An extensible options structure controlling checkout. Ensure that +you have entirely zeroed the structure, then set just the desired +options. This is used by ostree_repo_checkout_tree_at() which +supercedes previous separate enumeration usage in +ostree_repo_checkout_tree().</doc> + <source-position filename="ostree-repo-deprecated.h" line="58"/> + <field name="mode" writable="1"> + <type name="RepoCheckoutMode" c:type="OstreeRepoCheckoutMode"/> + </field> + <field name="overwrite_mode" writable="1"> + <type name="RepoCheckoutOverwriteMode" + c:type="OstreeRepoCheckoutOverwriteMode"/> + </field> + <field name="enable_uncompressed_cache" writable="1" bits="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="disable_fsync" writable="1" bits="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="process_whiteouts" writable="1" bits="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="no_copy_fallback" writable="1" bits="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="reserved" writable="1" bits="28"> + <type name="guint" c:type="guint"/> + </field> + <field name="subpath" writable="1"> + <type name="utf8" c:type="const char*"/> + </field> + <field name="devino_to_csum_cache" writable="1"> + <type name="RepoDevInoCache" c:type="OstreeRepoDevInoCache*"/> + </field> + <field name="unused_uints" writable="1"> + <array zero-terminated="0" fixed-size="6"> + <type name="guint" c:type="guint"/> + </array> + </field> + <field name="unused_ptrs" writable="1"> + <array zero-terminated="0" fixed-size="7"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <enumeration name="RepoCheckoutOverwriteMode" + c:type="OstreeRepoCheckoutOverwriteMode"> + <source-position filename="ostree-repo.h" line="931"/> + <member name="none" + value="0" + c:identifier="OSTREE_REPO_CHECKOUT_OVERWRITE_NONE"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="921">No special options</doc> + </member> + <member name="union_files" + value="1" + c:identifier="OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_FILES"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="922">When layering checkouts, unlink() and replace existing files, but do not modify existing directories (unless whiteouts are enabled, then directories are replaced)</doc> + </member> + <member name="add_files" + value="2" + c:identifier="OSTREE_REPO_CHECKOUT_OVERWRITE_ADD_FILES"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="923">Only add new files/directories</doc> + </member> + <member name="union_identical" + value="3" + c:identifier="OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_IDENTICAL"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="924">Like UNION_FILES, but error if files are not identical (requires hardlink checkouts)</doc> + </member> + </enumeration> + <callback name="RepoCommitFilter" c:type="OstreeRepoCommitFilter"> + <source-position filename="ostree-repo.h" line="669"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="667">#OstreeRepoCommitFilterResult saying whether or not to commit this file</doc> + <type name="RepoCommitFilterResult" + c:type="OstreeRepoCommitFilterResult"/> + </return-value> + <parameters> + <parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="662">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="663">Path to file</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="file_info" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="664">File information</doc> + <type name="Gio.FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1" + closure="3"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="665">User data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <enumeration name="RepoCommitFilterResult" + c:type="OstreeRepoCommitFilterResult"> + <source-position filename="ostree-repo.h" line="658"/> + <member name="allow" + value="0" + c:identifier="OSTREE_REPO_COMMIT_FILTER_ALLOW"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="652">Do commit this object</doc> + </member> + <member name="skip" + value="1" + c:identifier="OSTREE_REPO_COMMIT_FILTER_SKIP"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="653">Ignore this object</doc> + </member> + </enumeration> + <enumeration name="RepoCommitIterResult" + c:type="OstreeRepoCommitIterResult"> + <source-position filename="ostree-repo.h" line="1234"/> + <member name="error" + value="0" + c:identifier="OSTREE_REPO_COMMIT_ITER_RESULT_ERROR"> + </member> + <member name="end" + value="1" + c:identifier="OSTREE_REPO_COMMIT_ITER_RESULT_END"> + </member> + <member name="file" + value="2" + c:identifier="OSTREE_REPO_COMMIT_ITER_RESULT_FILE"> + </member> + <member name="dir" + value="3" + c:identifier="OSTREE_REPO_COMMIT_ITER_RESULT_DIR"> + </member> + </enumeration> + <record name="RepoCommitModifier" + c:type="OstreeRepoCommitModifier" + glib:type-name="OstreeRepoCommitModifier" + glib:get-type="ostree_repo_commit_modifier_get_type" + c:symbol-prefix="repo_commit_modifier"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="698">A structure allowing control over commits.</doc> + <source-position filename="ostree-repo.h" line="703"/> + <constructor name="new" c:identifier="ostree_repo_commit_modifier_new"> + <source-position filename="ostree-repo.h" line="706"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4298">A new commit modifier.</doc> + <type name="RepoCommitModifier" c:type="OstreeRepoCommitModifier*"/> + </return-value> + <parameters> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4293">Control options for filter</doc> + <type name="RepoCommitModifierFlags" + c:type="OstreeRepoCommitModifierFlags"/> + </parameter> + <parameter name="commit_filter" + transfer-ownership="none" + nullable="1" + allow-none="1" + scope="notified" + closure="2" + destroy="3"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4294">Function that can inspect individual files</doc> + <type name="RepoCommitFilter" c:type="OstreeRepoCommitFilter"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4295">User data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + <parameter name="destroy_notify" + transfer-ownership="none" + scope="async"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4296">A #GDestroyNotify</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + </parameters> + </constructor> + <method name="ref" c:identifier="ostree_repo_commit_modifier_ref"> + <source-position filename="ostree-repo.h" line="741"/> + <return-value transfer-ownership="full"> + <type name="RepoCommitModifier" c:type="OstreeRepoCommitModifier*"/> + </return-value> + <parameters> + <instance-parameter name="modifier" transfer-ownership="none"> + <type name="RepoCommitModifier" + c:type="OstreeRepoCommitModifier*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_devino_cache" + c:identifier="ostree_repo_commit_modifier_set_devino_cache" + version="2017.13"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4420">See the documentation for +`ostree_repo_devino_cache_new()`. This function can +then be used for later calls to +`ostree_repo_write_directory_to_mtree()` to optimize commits. + +Note if your process has multiple writers, you should use separate +`OSTreeRepo` instances if you want to also use this API. + +This function will add a reference to @cache without copying - you +should avoid further mutation of the cache.</doc> + <source-position filename="ostree-repo.h" line="737"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="modifier" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4422">Modifier</doc> + <type name="RepoCommitModifier" + c:type="OstreeRepoCommitModifier*"/> + </instance-parameter> + <parameter name="cache" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4423">A hash table caching device,inode to checksums</doc> + <type name="RepoDevInoCache" c:type="OstreeRepoDevInoCache*"/> + </parameter> + </parameters> + </method> + <method name="set_sepolicy" + c:identifier="ostree_repo_commit_modifier_set_sepolicy"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4370">If @policy is non-%NULL, use it to look up labels to use for +"security.selinux" extended attributes. + +Note that any policy specified this way operates in addition to any +extended attributes provided via +ostree_repo_commit_modifier_set_xattr_callback(). However if both +specify a value for "security.selinux", then the one from the +policy wins.</doc> + <source-position filename="ostree-repo.h" line="726"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="modifier" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4372">An #OstreeRepoCommitModifier</doc> + <type name="RepoCommitModifier" + c:type="OstreeRepoCommitModifier*"/> + </instance-parameter> + <parameter name="sepolicy" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4373">Policy to use for labeling</doc> + <type name="SePolicy" c:type="OstreeSePolicy*"/> + </parameter> + </parameters> + </method> + <method name="set_sepolicy_from_commit" + c:identifier="ostree_repo_commit_modifier_set_sepolicy_from_commit" + version="2020.4" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4392">In many cases, one wants to create a "derived" commit from base commit. +SELinux policy labels are part of that base commit. This API allows +one to easily set up SELinux labeling from a base commit.</doc> + <source-position filename="ostree-repo.h" line="730"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="modifier" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4394">Commit modifier</doc> + <type name="RepoCommitModifier" + c:type="OstreeRepoCommitModifier*"/> + </instance-parameter> + <parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4395">OSTree repo containing @rev</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="rev" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4396">Find SELinux policy from this base commit</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_xattr_callback" + c:identifier="ostree_repo_commit_modifier_set_xattr_callback"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4347">If set, this function should return extended attributes to use for +the given path. This is useful for things like ACLs and SELinux, +where a build system can label the files as it's committing to the +repository.</doc> + <source-position filename="ostree-repo.h" line="720"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="modifier" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4349">An #OstreeRepoCommitModifier</doc> + <type name="RepoCommitModifier" + c:type="OstreeRepoCommitModifier*"/> + </instance-parameter> + <parameter name="callback" + transfer-ownership="none" + scope="notified" + closure="2" + destroy="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4350">Function to be invoked, should return extended attributes for path</doc> + <type name="RepoCommitModifierXattrCallback" + c:type="OstreeRepoCommitModifierXattrCallback"/> + </parameter> + <parameter name="destroy" transfer-ownership="none" scope="async"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4351">Destroy notification</doc> + <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-commit.c" + line="4352">Data for @callback:</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="unref" c:identifier="ostree_repo_commit_modifier_unref"> + <source-position filename="ostree-repo.h" line="743"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="modifier" transfer-ownership="none"> + <type name="RepoCommitModifier" + c:type="OstreeRepoCommitModifier*"/> + </instance-parameter> + </parameters> + </method> + </record> + <bitfield name="RepoCommitModifierFlags" + c:type="OstreeRepoCommitModifierFlags"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="674">Flags modifying commit behavior. In bare-user-only mode, @OSTREE_REPO_COMMIT_MODIFIER_FLAGS_CANONICAL_PERMISSIONS +and @OSTREE_REPO_COMMIT_MODIFIER_FLAGS_SKIP_XATTRS are automatically enabled.</doc> + <source-position filename="ostree-repo.h" line="696"/> + <member name="none" + value="0" + c:identifier="OSTREE_REPO_COMMIT_MODIFIER_FLAGS_NONE"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="676">No special flags</doc> + </member> + <member name="skip_xattrs" + value="1" + c:identifier="OSTREE_REPO_COMMIT_MODIFIER_FLAGS_SKIP_XATTRS"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="677">Do not process extended attributes</doc> + </member> + <member name="generate_sizes" + value="2" + c:identifier="OSTREE_REPO_COMMIT_MODIFIER_FLAGS_GENERATE_SIZES"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="678">Generate size information.</doc> + </member> + <member name="canonical_permissions" + value="4" + c:identifier="OSTREE_REPO_COMMIT_MODIFIER_FLAGS_CANONICAL_PERMISSIONS"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="679">Canonicalize permissions.</doc> + </member> + <member name="error_on_unlabeled" + value="8" + c:identifier="OSTREE_REPO_COMMIT_MODIFIER_FLAGS_ERROR_ON_UNLABELED"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="680">Emit an error if configured SELinux policy does not provide a label</doc> + </member> + <member name="consume" + value="16" + c:identifier="OSTREE_REPO_COMMIT_MODIFIER_FLAGS_CONSUME"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="681">Delete added files/directories after commit; Since: 2017.13</doc> + </member> + <member name="devino_canonical" + value="32" + c:identifier="OSTREE_REPO_COMMIT_MODIFIER_FLAGS_DEVINO_CANONICAL"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="682">If a devino cache hit is found, skip modifier filters (non-directories only); Since: 2017.14</doc> + </member> + </bitfield> + <callback name="RepoCommitModifierXattrCallback" + c:type="OstreeRepoCommitModifierXattrCallback"> + <source-position filename="ostree-repo.h" line="714"/> + <return-value transfer-ownership="full"> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="repo" transfer-ownership="none"> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="file_info" transfer-ownership="none"> + <type name="Gio.FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1" + closure="3"> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <bitfield name="RepoCommitState" + version="2015.7" + c:type="OstreeRepoCommitState"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="250">Flags representing the state of a commit in the local repository, as returned +by ostree_repo_load_commit().</doc> + <source-position filename="ostree-repo.h" line="268"/> + <member name="normal" + value="0" + c:identifier="OSTREE_REPO_COMMIT_STATE_NORMAL"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="252">Commit is complete. This is the default. + (Since: 2017.14.)</doc> + </member> + <member name="partial" + value="1" + c:identifier="OSTREE_REPO_COMMIT_STATE_PARTIAL"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="254">One or more objects are missing from the + local copy of the commit, but metadata is present. (Since: 2015.7.)</doc> + </member> + <member name="fsck_partial" + value="2" + c:identifier="OSTREE_REPO_COMMIT_STATE_FSCK_PARTIAL"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="256">One or more objects are missing from the + local copy of the commit, due to an fsck --delete. (Since: 2019.4.)</doc> + </member> + </bitfield> + <bitfield name="RepoCommitTraverseFlags" + c:type="OstreeRepoCommitTraverseFlags"> + <source-position filename="ostree-repo.h" line="1129"/> + <member name="none" + value="1" + c:identifier="OSTREE_REPO_COMMIT_TRAVERSE_FLAG_NONE"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1123">No special options for traverse</doc> + </member> + <member name="commit_only" + value="2" + c:identifier="OSTREE_REPO_COMMIT_TRAVERSE_FLAG_COMMIT_ONLY"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1124">Traverse and retrieve only commit objects. (Since: 2022.2)</doc> + </member> + </bitfield> + <record name="RepoCommitTraverseIter" + c:type="OstreeRepoCommitTraverseIter"> + <source-position filename="ostree-repo.h" line="1209"/> + <field name="initialized" writable="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="dummy" writable="1"> + <array zero-terminated="0" fixed-size="10"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + <field name="dummy_checksum_data" writable="1"> + <array zero-terminated="0" fixed-size="130"> + <type name="gchar" c:type="char"/> + </array> + </field> + <method name="clear" + c:identifier="ostree_repo_commit_traverse_iter_clear"> + <source-position filename="ostree-repo.h" line="1253"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <type name="RepoCommitTraverseIter" + c:type="OstreeRepoCommitTraverseIter*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_dir" + c:identifier="ostree_repo_commit_traverse_iter_get_dir"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="233">Return information on the current directory. This function may +only be called if %OSTREE_REPO_COMMIT_ITER_RESULT_DIR was returned +from ostree_repo_commit_traverse_iter_next().</doc> + <source-position filename="ostree-repo.h" line="1247"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="235">An iter</doc> + <type name="RepoCommitTraverseIter" + c:type="OstreeRepoCommitTraverseIter*"/> + </instance-parameter> + <parameter name="out_name" + direction="out" + caller-allocates="0" + transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="236">Name of current dir</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="out_content_checksum" + direction="out" + caller-allocates="0" + transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="237">Checksum of current content</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="out_meta_checksum" + direction="out" + caller-allocates="0" + transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="238">Checksum of current metadata</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="get_file" + c:identifier="ostree_repo_commit_traverse_iter_get_file"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="212">Return information on the current file. This function may only be +called if %OSTREE_REPO_COMMIT_ITER_RESULT_FILE was returned from +ostree_repo_commit_traverse_iter_next().</doc> + <source-position filename="ostree-repo.h" line="1242"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="214">An iter</doc> + <type name="RepoCommitTraverseIter" + c:type="OstreeRepoCommitTraverseIter*"/> + </instance-parameter> + <parameter name="out_name" + direction="out" + caller-allocates="0" + transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="215">Name of current file</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="out_checksum" + direction="out" + caller-allocates="0" + transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="216">Checksum of current file</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="init_commit" + c:identifier="ostree_repo_commit_traverse_iter_init_commit" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="40">Initialize (in place) an iterator over the root of a commit object.</doc> + <source-position filename="ostree-repo.h" line="1215"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="42">An iter</doc> + <type name="RepoCommitTraverseIter" + c:type="OstreeRepoCommitTraverseIter*"/> + </instance-parameter> + <parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="43">A repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="commit" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="44">Variant of type %OSTREE_OBJECT_TYPE_COMMIT</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="45">Flags</doc> + <type name="RepoCommitTraverseFlags" + c:type="OstreeRepoCommitTraverseFlags"/> + </parameter> + </parameters> + </method> + <method name="init_dirtree" + c:identifier="ostree_repo_commit_traverse_iter_init_dirtree" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="84">Initialize (in place) an iterator over a directory tree.</doc> + <source-position filename="ostree-repo.h" line="1223"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="86">An iter</doc> + <type name="RepoCommitTraverseIter" + c:type="OstreeRepoCommitTraverseIter*"/> + </instance-parameter> + <parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="87">A repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="dirtree" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="88">Variant of type %OSTREE_OBJECT_TYPE_DIR_TREE</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="89">Flags</doc> + <type name="RepoCommitTraverseFlags" + c:type="OstreeRepoCommitTraverseFlags"/> + </parameter> + </parameters> + </method> + <method name="next" + c:identifier="ostree_repo_commit_traverse_iter_next" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="113">Step the interator to the next item. Files will be returned first, +then subdirectories. Call this in a loop; upon encountering +%OSTREE_REPO_COMMIT_ITER_RESULT_END, there will be no more files or +directories. If %OSTREE_REPO_COMMIT_ITER_RESULT_DIR is returned, +then call ostree_repo_commit_traverse_iter_get_dir() to retrieve +data for that directory. Similarly, if +%OSTREE_REPO_COMMIT_ITER_RESULT_FILE is returned, call +ostree_repo_commit_traverse_iter_get_file(). + +If %OSTREE_REPO_COMMIT_ITER_RESULT_ERROR is returned, it is a +program error to call any further API on @iter except for +ostree_repo_commit_traverse_iter_clear().</doc> + <source-position filename="ostree-repo.h" line="1237"/> + <return-value transfer-ownership="none"> + <type name="RepoCommitIterResult" + c:type="OstreeRepoCommitIterResult"/> + </return-value> + <parameters> + <instance-parameter name="iter" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="115">An iter</doc> + <type name="RepoCommitTraverseIter" + c:type="OstreeRepoCommitTraverseIter*"/> + </instance-parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-traverse.c" + line="116">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <function name="cleanup" + c:identifier="ostree_repo_commit_traverse_iter_cleanup"> + <source-position filename="ostree-repo.h" line="1256"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="p" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <type name="gpointer" c:type="void*"/> + </parameter> + </parameters> + </function> + </record> + <record name="RepoDevInoCache" + c:type="OstreeRepoDevInoCache" + glib:type-name="OstreeRepoDevInoCache" + glib:get-type="ostree_repo_devino_cache_get_type" + c:symbol-prefix="repo_devino_cache"> + <source-position filename="ostree-types.h" line="33"/> + <constructor name="new" c:identifier="ostree_repo_devino_cache_new"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1447">OSTree has support for pairing ostree_repo_checkout_tree_at() using +hardlinks in combination with a later +ostree_repo_write_directory_to_mtree() using a (normally modified) +directory. In order for OSTree to optimally detect just the new +files, use this function and fill in the `devino_to_csum_cache` +member of `OstreeRepoCheckoutAtOptions`, then call +ostree_repo_commit_set_devino_cache().</doc> + <source-position filename="ostree-repo.h" line="1010"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-checkout.c" + line="1458">Newly allocated cache</doc> + <type name="RepoDevInoCache" c:type="OstreeRepoDevInoCache*"/> + </return-value> + </constructor> + <method name="ref" c:identifier="ostree_repo_devino_cache_ref"> + <source-position filename="ostree-repo.h" line="1012"/> + <return-value transfer-ownership="full"> + <type name="RepoDevInoCache" c:type="OstreeRepoDevInoCache*"/> + </return-value> + <parameters> + <instance-parameter name="cache" transfer-ownership="none"> + <type name="RepoDevInoCache" c:type="OstreeRepoDevInoCache*"/> + </instance-parameter> + </parameters> + </method> + <method name="unref" c:identifier="ostree_repo_devino_cache_unref"> + <source-position filename="ostree-repo.h" line="1014"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="cache" transfer-ownership="none"> + <type name="RepoDevInoCache" c:type="OstreeRepoDevInoCache*"/> + </instance-parameter> + </parameters> + </method> + </record> + <record name="RepoExportArchiveOptions" + c:type="OstreeRepoExportArchiveOptions" + introspectable="0"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="836">An extensible options structure controlling archive creation. Ensure that +you have entirely zeroed the structure, then set just the desired +options. This is used by ostree_repo_export_tree_to_archive().</doc> + <source-position filename="ostree-repo.h" line="855"/> + <field name="disable_xattrs" writable="1" bits="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="reserved" writable="1" bits="31"> + <type name="guint" c:type="guint"/> + </field> + <field name="timestamp_secs" writable="1"> + <type name="guint64" c:type="guint64"/> + </field> + <field name="unused_uint" writable="1"> + <array zero-terminated="0" fixed-size="8"> + <type name="guint" c:type="guint"/> + </array> + </field> + <field name="path_prefix" writable="1"> + <type name="utf8" c:type="char*"/> + </field> + <field name="unused_ptrs" writable="1"> + <array zero-terminated="0" fixed-size="7"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <class name="RepoFile" + c:symbol-prefix="repo_file" + c:type="OstreeRepoFile" + parent="GObject.Object" + glib:type-name="OstreeRepoFile" + glib:get-type="ostree_repo_file_get_type" + glib:type-struct="RepoFileClass"> + <source-position filename="ostree-repo-file.h" line="40"/> + <implements name="Gio.File"/> + <method name="ensure_resolved" + c:identifier="ostree_repo_file_ensure_resolved" + throws="1"> + <source-position filename="ostree-repo-file.h" line="46"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_checksum" c:identifier="ostree_repo_file_get_checksum"> + <source-position filename="ostree-repo-file.h" line="76"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_repo" c:identifier="ostree_repo_file_get_repo"> + <source-position filename="ostree-repo-file.h" line="56"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-file.c" + line="362">Repository</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_root" c:identifier="ostree_repo_file_get_root"> + <source-position filename="ostree-repo-file.h" line="58"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-file.c" + line="374">The root directory for the commit referenced by this file</doc> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_xattrs" + c:identifier="ostree_repo_file_get_xattrs" + throws="1"> + <source-position filename="ostree-repo-file.h" line="50"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-file.c" + line="295">#OstreeRepoFile</doc> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </instance-parameter> + <parameter name="out_xattrs" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-file.c" + line="296">the extended attributes</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-file.c" + line="297">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="tree_find_child" + c:identifier="ostree_repo_file_tree_find_child"> + <source-position filename="ostree-repo-file.h" line="79"/> + <return-value transfer-ownership="none"> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-file.c" + line="734">#OstreeRepoFile</doc> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </instance-parameter> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-file.c" + line="735">name of the child</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="is_dir" + direction="out" + caller-allocates="1" + transfer-ownership="none"> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + <parameter name="out_container" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + </parameters> + </method> + <method name="tree_get_contents" + c:identifier="ostree_repo_file_tree_get_contents"> + <source-position filename="ostree-repo-file.h" line="71"/> + <return-value transfer-ownership="full"> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="tree_get_contents_checksum" + c:identifier="ostree_repo_file_tree_get_contents_checksum"> + <source-position filename="ostree-repo-file.h" line="66"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="tree_get_metadata" + c:identifier="ostree_repo_file_tree_get_metadata"> + <source-position filename="ostree-repo-file.h" line="73"/> + <return-value transfer-ownership="full"> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="tree_get_metadata_checksum" + c:identifier="ostree_repo_file_tree_get_metadata_checksum"> + <source-position filename="ostree-repo-file.h" line="68"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </instance-parameter> + </parameters> + </method> + <method name="tree_query_child" + c:identifier="ostree_repo_file_tree_query_child" + throws="1"> + <source-position filename="ostree-repo-file.h" line="85"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-file.c" + line="786">#OstreeRepoFile</doc> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </instance-parameter> + <parameter name="n" transfer-ownership="none"> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="attributes" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <type name="Gio.FileQueryInfoFlags" c:type="GFileQueryInfoFlags"/> + </parameter> + <parameter name="out_info" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <type name="Gio.FileInfo" c:type="GFileInfo**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-file.c" + line="791">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="tree_set_metadata" + c:identifier="ostree_repo_file_tree_set_metadata"> + <source-position filename="ostree-repo-file.h" line="61"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="RepoFile" c:type="OstreeRepoFile*"/> + </instance-parameter> + <parameter name="checksum" transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="metadata" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + </class> + <record name="RepoFileClass" + c:type="OstreeRepoFileClass" + glib:is-gtype-struct-for="RepoFile"> + <source-position filename="ostree-repo-file.h" line="40"/> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <record name="RepoFileEnumerator" + c:type="OstreeRepoFileEnumerator" + disguised="1"> + <source-position filename="ostree-repo-file-enumerator.h" line="35"/> + </record> + <record name="RepoFileEnumeratorClass" + c:type="OstreeRepoFileEnumeratorClass"> + <source-position filename="ostree-repo-file-enumerator.h" line="41"/> + <field name="parent_class" writable="1"> + <type name="Gio.FileEnumeratorClass" c:type="GFileEnumeratorClass"/> + </field> + </record> + <interface name="RepoFinder" + c:symbol-prefix="repo_finder" + c:type="OstreeRepoFinder" + glib:type-name="OstreeRepoFinder" + glib:get-type="ostree_repo_finder_get_type" + glib:type-struct="RepoFinderInterface"> + <source-position filename="ostree-repo-finder.h" line="65"/> + <function name="resolve_all_async" + c:identifier="ostree_repo_finder_resolve_all_async" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="243">A version of ostree_repo_finder_resolve_async() which queries one or more +@finders in parallel and combines the results.</doc> + <source-position filename="ostree-repo-finder.h" line="80"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="finders" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="245">non-empty array of #OstreeRepoFinders</doc> + <array c:type="OstreeRepoFinder* const*"> + <type name="RepoFinder" c:type="OstreeRepoFinder*"/> + </array> + </parameter> + <parameter name="refs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="246">non-empty array of collection–ref pairs to find remotes for</doc> + <array c:type="const OstreeCollectionRef* const*"> + <type name="CollectionRef" c:type="OstreeCollectionRef*"/> + </array> + </parameter> + <parameter name="parent_repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="247">the local repository which the refs are being resolved for, + which provides configuration information and GPG keys</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="249">a #GCancellable, or %NULL</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" + transfer-ownership="none" + nullable="1" + allow-none="1" + scope="async" + closure="5"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="250">asynchronous completion callback</doc> + <type name="Gio.AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="251">data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="resolve_all_finish" + c:identifier="ostree_repo_finder_resolve_all_finish" + version="2018.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="404">Get the results from a ostree_repo_finder_resolve_all_async() operation.</doc> + <source-position filename="ostree-repo-finder.h" line="87"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="411">array of zero + or more results</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="RepoFinderResult"/> + </array> + </return-value> + <parameters> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="406">#GAsyncResult from the callback</doc> + <type name="Gio.AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </function> + <virtual-method name="resolve_async" + invoker="resolve_async" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="107">Find reachable remote URIs which claim to provide any of the given @refs. The +specific method for finding the remotes depends on the #OstreeRepoFinder +implementation. + +Any remote which is found and which claims to support any of the given @refs +will be returned in the results. It is possible that a remote claims to +support a given ref, but turns out not to — it is not possible to verify this +until ostree_repo_pull_from_remotes_async() is called. + +The returned results will be sorted with the most useful first — this is +typically the remote which claims to provide the most @refs, at the lowest +latency. + +Each result contains a mapping of @refs to the checksums of the commits +which the result provides. If the result provides the latest commit for a ref +across all of the results, the checksum will be set. Otherwise, if the +result provides an outdated commit, or doesn’t provide a given ref at all, +the checksum will not be set. Results which provide none of the requested +@refs may be listed with an empty refs map. + +Pass the results to ostree_repo_pull_from_remotes_async() to pull the given +@refs from those remotes.</doc> + <source-position filename="ostree-repo-finder.h" line="56"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="109">an #OstreeRepoFinder</doc> + <type name="RepoFinder" c:type="OstreeRepoFinder*"/> + </instance-parameter> + <parameter name="refs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="110">non-empty array of collection–ref pairs to find remotes for</doc> + <array c:type="const OstreeCollectionRef* const*"> + <type name="CollectionRef" c:type="OstreeCollectionRef*"/> + </array> + </parameter> + <parameter name="parent_repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="111">the local repository which the refs are being resolved for, + which provides configuration information and GPG keys</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="113">a #GCancellable, or %NULL</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" + transfer-ownership="none" + nullable="1" + allow-none="1" + scope="async" + closure="4"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="114">asynchronous completion callback</doc> + <type name="Gio.AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1" + closure="4"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="115">data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="resolve_finish" + invoker="resolve_finish" + version="2018.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="188">Get the results from a ostree_repo_finder_resolve_async() operation.</doc> + <source-position filename="ostree-repo-finder.h" line="62"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="196">array of zero + or more results</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="RepoFinderResult"/> + </array> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="190">an #OstreeRepoFinder</doc> + <type name="RepoFinder" c:type="OstreeRepoFinder*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="191">#GAsyncResult from the callback</doc> + <type name="Gio.AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </virtual-method> + <method name="resolve_async" + c:identifier="ostree_repo_finder_resolve_async" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="107">Find reachable remote URIs which claim to provide any of the given @refs. The +specific method for finding the remotes depends on the #OstreeRepoFinder +implementation. + +Any remote which is found and which claims to support any of the given @refs +will be returned in the results. It is possible that a remote claims to +support a given ref, but turns out not to — it is not possible to verify this +until ostree_repo_pull_from_remotes_async() is called. + +The returned results will be sorted with the most useful first — this is +typically the remote which claims to provide the most @refs, at the lowest +latency. + +Each result contains a mapping of @refs to the checksums of the commits +which the result provides. If the result provides the latest commit for a ref +across all of the results, the checksum will be set. Otherwise, if the +result provides an outdated commit, or doesn’t provide a given ref at all, +the checksum will not be set. Results which provide none of the requested +@refs may be listed with an empty refs map. + +Pass the results to ostree_repo_pull_from_remotes_async() to pull the given +@refs from those remotes.</doc> + <source-position filename="ostree-repo-finder.h" line="68"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="109">an #OstreeRepoFinder</doc> + <type name="RepoFinder" c:type="OstreeRepoFinder*"/> + </instance-parameter> + <parameter name="refs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="110">non-empty array of collection–ref pairs to find remotes for</doc> + <array c:type="const OstreeCollectionRef* const*"> + <type name="CollectionRef" c:type="OstreeCollectionRef*"/> + </array> + </parameter> + <parameter name="parent_repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="111">the local repository which the refs are being resolved for, + which provides configuration information and GPG keys</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="113">a #GCancellable, or %NULL</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" + transfer-ownership="none" + nullable="1" + allow-none="1" + scope="async" + closure="4"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="114">asynchronous completion callback</doc> + <type name="Gio.AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="115">data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="resolve_finish" + c:identifier="ostree_repo_finder_resolve_finish" + version="2018.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="188">Get the results from a ostree_repo_finder_resolve_async() operation.</doc> + <source-position filename="ostree-repo-finder.h" line="75"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="196">array of zero + or more results</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="RepoFinderResult"/> + </array> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="190">an #OstreeRepoFinder</doc> + <type name="RepoFinder" c:type="OstreeRepoFinder*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="191">#GAsyncResult from the callback</doc> + <type name="Gio.AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + </interface> + <class name="RepoFinderAvahi" + c:symbol-prefix="repo_finder_avahi" + c:type="OstreeRepoFinderAvahi" + parent="GObject.Object" + glib:type-name="OstreeRepoFinderAvahi" + glib:get-type="ostree_repo_finder_avahi_get_type" + glib:type-struct="RepoFinderAvahiClass"> + <source-position filename="ostree-repo-finder-avahi.h" line="45"/> + <implements name="RepoFinder"/> + <constructor name="new" + c:identifier="ostree_repo_finder_avahi_new" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-finder-avahi.c" + line="1358">Create a new #OstreeRepoFinderAvahi instance. It is intended that one such +instance be created per process, and it be used to answer all resolution +requests from #OstreeRepos. + +The calling code is responsible for ensuring that @context is iterated while +the #OstreeRepoFinderAvahi is running (after ostree_repo_finder_avahi_start() +is called). This may be done from any thread. + +If @context is %NULL, the current thread-default #GMainContext is used.</doc> + <source-position filename="ostree-repo-finder-avahi.h" line="52"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-finder-avahi.c" + line="1373">a new #OstreeRepoFinderAvahi</doc> + <type name="RepoFinderAvahi" c:type="OstreeRepoFinderAvahi*"/> + </return-value> + <parameters> + <parameter name="context" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder-avahi.c" + line="1360">a #GMainContext for processing Avahi + events in, or %NULL to use the current thread-default</doc> + <type name="GLib.MainContext" c:type="GMainContext*"/> + </parameter> + </parameters> + </constructor> + <method name="start" + c:identifier="ostree_repo_finder_avahi_start" + version="2018.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder-avahi.c" + line="1401">Start monitoring the local network for peers who are advertising OSTree +repositories, using Avahi. In order for this to work, the #GMainContext +passed to @self at construction time must be iterated (so it will typically +be the global #GMainContext, or be a separate #GMainContext in a worker +thread). + +This will return an error (%G_IO_ERROR_FAILED) if initialisation fails, or if +Avahi support is not available (%G_IO_ERROR_NOT_SUPPORTED). In either case, +the #OstreeRepoFinderAvahi instance is useless afterwards and should be +destroyed. + +Call ostree_repo_finder_avahi_stop() to stop the repo finder. + +It is an error to call this function multiple times on the same +#OstreeRepoFinderAvahi instance, or to call it after +ostree_repo_finder_avahi_stop().</doc> + <source-position filename="ostree-repo-finder-avahi.h" line="55"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder-avahi.c" + line="1403">an #OstreeRepoFinderAvahi</doc> + <type name="RepoFinderAvahi" c:type="OstreeRepoFinderAvahi*"/> + </instance-parameter> + </parameters> + </method> + <method name="stop" + c:identifier="ostree_repo_finder_avahi_stop" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-finder-avahi.c" + line="1490">Stop monitoring the local network for peers who are advertising OSTree +repositories. If any resolve tasks (from ostree_repo_finder_resolve_async()) +are in progress, they will be cancelled and will return %G_IO_ERROR_CANCELLED. + +Call ostree_repo_finder_avahi_start() to start the repo finder. + +It is an error to call this function multiple times on the same +#OstreeRepoFinderAvahi instance, or to call it before +ostree_repo_finder_avahi_start().</doc> + <source-position filename="ostree-repo-finder-avahi.h" line="59"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder-avahi.c" + line="1492">an #OstreeRepoFinderAvahi</doc> + <type name="RepoFinderAvahi" c:type="OstreeRepoFinderAvahi*"/> + </instance-parameter> + </parameters> + </method> + </class> + <record name="RepoFinderAvahiClass" + c:type="OstreeRepoFinderAvahiClass" + glib:is-gtype-struct-for="RepoFinderAvahi"> + <source-position filename="ostree-repo-finder-avahi.h" line="45"/> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <class name="RepoFinderConfig" + c:symbol-prefix="repo_finder_config" + c:type="OstreeRepoFinderConfig" + parent="GObject.Object" + glib:type-name="OstreeRepoFinderConfig" + glib:get-type="ostree_repo_finder_config_get_type" + glib:type-struct="RepoFinderConfigClass"> + <source-position filename="ostree-repo-finder-config.h" line="45"/> + <implements name="RepoFinder"/> + <constructor name="new" + c:identifier="ostree_repo_finder_config_new" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-finder-config.c" + line="229">Create a new #OstreeRepoFinderConfig.</doc> + <source-position filename="ostree-repo-finder-config.h" line="52"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-finder-config.c" + line="234">a new #OstreeRepoFinderConfig</doc> + <type name="RepoFinderConfig" c:type="OstreeRepoFinderConfig*"/> + </return-value> + </constructor> + </class> + <record name="RepoFinderConfigClass" + c:type="OstreeRepoFinderConfigClass" + glib:is-gtype-struct-for="RepoFinderConfig"> + <source-position filename="ostree-repo-finder-config.h" line="45"/> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <record name="RepoFinderInterface" + c:type="OstreeRepoFinderInterface" + glib:is-gtype-struct-for="RepoFinder"> + <source-position filename="ostree-repo-finder.h" line="65"/> + <field name="g_iface"> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="resolve_async"> + <callback name="resolve_async"> + <source-position filename="ostree-repo-finder.h" line="56"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="109">an #OstreeRepoFinder</doc> + <type name="RepoFinder" c:type="OstreeRepoFinder*"/> + </parameter> + <parameter name="refs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="110">non-empty array of collection–ref pairs to find remotes for</doc> + <array c:type="const OstreeCollectionRef* const*"> + <type name="CollectionRef" c:type="OstreeCollectionRef*"/> + </array> + </parameter> + <parameter name="parent_repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="111">the local repository which the refs are being resolved for, + which provides configuration information and GPG keys</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="113">a #GCancellable, or %NULL</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" + transfer-ownership="none" + nullable="1" + allow-none="1" + scope="async" + closure="5"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="114">asynchronous completion callback</doc> + <type name="Gio.AsyncReadyCallback" + c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1" + closure="5"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="115">data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + </field> + <field name="resolve_finish"> + <callback name="resolve_finish" throws="1"> + <source-position filename="ostree-repo-finder.h" line="62"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="196">array of zero + or more results</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="RepoFinderResult"/> + </array> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="190">an #OstreeRepoFinder</doc> + <type name="RepoFinder" c:type="OstreeRepoFinder*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="191">#GAsyncResult from the callback</doc> + <type name="Gio.AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <class name="RepoFinderMount" + c:symbol-prefix="repo_finder_mount" + c:type="OstreeRepoFinderMount" + parent="GObject.Object" + glib:type-name="OstreeRepoFinderMount" + glib:get-type="ostree_repo_finder_mount_get_type" + glib:type-struct="RepoFinderMountClass"> + <source-position filename="ostree-repo-finder-mount.h" line="45"/> + <implements name="RepoFinder"/> + <constructor name="new" + c:identifier="ostree_repo_finder_mount_new" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-finder-mount.c" + line="671">Create a new #OstreeRepoFinderMount, using the given @monitor to look up +volumes. If @monitor is %NULL, the monitor from g_volume_monitor_get() will +be used.</doc> + <source-position filename="ostree-repo-finder-mount.h" line="52"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-finder-mount.c" + line="680">a new #OstreeRepoFinderMount</doc> + <type name="RepoFinderMount" c:type="OstreeRepoFinderMount*"/> + </return-value> + <parameters> + <parameter name="monitor" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder-mount.c" + line="673">volume monitor to use, or %NULL to use + the system default</doc> + <type name="Gio.VolumeMonitor" c:type="GVolumeMonitor*"/> + </parameter> + </parameters> + </constructor> + <property name="monitor" + version="2018.6" + writable="1" + construct-only="1" + transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder-mount.c" + line="645">Volume monitor to use to look up mounted volumes when queried.</doc> + <type name="Gio.VolumeMonitor"/> + </property> + </class> + <record name="RepoFinderMountClass" + c:type="OstreeRepoFinderMountClass" + glib:is-gtype-struct-for="RepoFinderMount"> + <source-position filename="ostree-repo-finder-mount.h" line="45"/> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <class name="RepoFinderOverride" + c:symbol-prefix="repo_finder_override" + c:type="OstreeRepoFinderOverride" + parent="GObject.Object" + glib:type-name="OstreeRepoFinderOverride" + glib:get-type="ostree_repo_finder_override_get_type" + glib:type-struct="RepoFinderOverrideClass"> + <source-position filename="ostree-repo-finder-override.h" line="45"/> + <implements name="RepoFinder"/> + <constructor name="new" + c:identifier="ostree_repo_finder_override_new" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-finder-override.c" + line="291">Create a new #OstreeRepoFinderOverride.</doc> + <source-position filename="ostree-repo-finder-override.h" line="52"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-finder-override.c" + line="296">a new #OstreeRepoFinderOverride</doc> + <type name="RepoFinderOverride" c:type="OstreeRepoFinderOverride*"/> + </return-value> + </constructor> + <method name="add_uri" + c:identifier="ostree_repo_finder_override_add_uri" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-finder-override.c" + line="305">Add the given @uri to the set of URIs which the repo finder will search for +matching refs when ostree_repo_finder_resolve_async() is called on it.</doc> + <source-position filename="ostree-repo-finder-override.h" line="55"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="RepoFinderOverride" + c:type="OstreeRepoFinderOverride*"/> + </instance-parameter> + <parameter name="uri" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder-override.c" + line="307">URI to add to the repo finder</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </method> + </class> + <record name="RepoFinderOverrideClass" + c:type="OstreeRepoFinderOverrideClass" + glib:is-gtype-struct-for="RepoFinderOverride"> + <source-position filename="ostree-repo-finder-override.h" line="45"/> + <field name="parent_class"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <record name="RepoFinderResult" + c:type="OstreeRepoFinderResult" + version="2018.6" + glib:type-name="OstreeRepoFinderResult" + glib:get-type="ostree_repo_finder_result_get_type" + c:symbol-prefix="repo_finder_result"> + <doc xml:space="preserve" + filename="ostree-repo-finder.h" + line="90">#OstreeRepoFinderResult gives a single result from an +ostree_repo_finder_resolve_async() or ostree_repo_finder_resolve_all_async() +operation. This represents a single remote which provides none, some or all +of the refs being resolved. The structure includes various bits of metadata +which allow ostree_repo_pull_from_remotes_async() (for example) to prioritise +how to pull the refs. + +An #OstreeRepoFinderResult is immutable after construction. + +The @priority is used as one input of many to ordering functions like +ostree_repo_finder_result_compare(). + +@ref_to_checksum indicates which refs (out of the ones queried for as inputs +to ostree_repo_finder_resolve_async()) are provided by this remote. The refs +are present as keys (of type #OstreeCollectionRef), and the corresponding values +are the checksums of the commits the remote currently has for those refs. (These +might not be the latest commits available out of all results.) A +checksum may be %NULL if the remote does not advertise the corresponding ref. +After ostree_repo_finder_resolve_async() has been called, the commit metadata +should be available locally, so the details for each checksum can be looked +up using ostree_repo_load_commit(). + +@ref_to_timestamp provides timestamps for the set of refs in +@ref_to_checksum. The refs are keys (of type #OstreeCollectionRef) and the +values are guint64 pointers with the timestamp associated with the checksum +provided in @ref_to_checksum. @ref_to_timestamp can be %NULL, and when it's +not, the timestamps are zero when any of the following conditions are met: +(1) the override-commit-ids option was used on +ostree_repo_find_remotes_async (2) there was an error in trying to get the +commit metadata (3) the checksum for this ref is %NULL in @ref_to_checksum.</doc> + <source-position filename="ostree-repo-finder.h" line="149"/> + <field name="remote" writable="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.h" + line="92">#OstreeRemote which contains the transport details for the result, + such as its URI and GPG key</doc> + <type name="Remote" c:type="OstreeRemote*"/> + </field> + <field name="finder" writable="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.h" + line="94">the #OstreeRepoFinder instance which produced this result</doc> + <type name="RepoFinder" c:type="OstreeRepoFinder*"/> + </field> + <field name="priority" writable="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.h" + line="95">static priority of the result, where higher numbers indicate lower + priority</doc> + <type name="gint" c:type="gint"/> + </field> + <field name="ref_to_checksum" writable="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.h" + line="97">map of collection–ref + pairs to checksums provided by this remote; values may be %NULL to + indicate this remote doesn’t provide that ref</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="CollectionRef"/> + <type name="utf8"/> + </type> + </field> + <field name="summary_last_modified" writable="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.h" + line="102">Unix timestamp (seconds since the epoch, UTC) when + the summary file on the remote was last modified, or `0` if unknown</doc> + <type name="guint64" c:type="guint64"/> + </field> + <field name="ref_to_timestamp" writable="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.h" + line="100">map of + collection–ref pairs to timestamps; values may be 0 for various reasons</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="CollectionRef"/> + <type name="guint64"/> + </type> + </field> + <field name="padding" readable="0" private="1"> + <array zero-terminated="0" fixed-size="3"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + <constructor name="new" + c:identifier="ostree_repo_finder_result_new" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="428">Create a new #OstreeRepoFinderResult instance. The semantics for the arguments +are as described in the #OstreeRepoFinderResult documentation.</doc> + <source-position filename="ostree-repo-finder.h" line="155"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="447">a new #OstreeRepoFinderResult</doc> + <type name="RepoFinderResult" c:type="OstreeRepoFinderResult*"/> + </return-value> + <parameters> + <parameter name="remote" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="430">an #OstreeRemote containing the transport details + for the result</doc> + <type name="Remote" c:type="OstreeRemote*"/> + </parameter> + <parameter name="finder" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="432">the #OstreeRepoFinder instance which produced the + result</doc> + <type name="RepoFinder" c:type="OstreeRepoFinder*"/> + </parameter> + <parameter name="priority" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="434">static priority of the result, where higher numbers indicate lower + priority</doc> + <type name="gint" c:type="gint"/> + </parameter> + <parameter name="ref_to_checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="436"> + map of collection–ref pairs to checksums provided by this result</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="CollectionRef"/> + <type name="utf8"/> + </type> + </parameter> + <parameter name="ref_to_timestamp" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="438">map of collection–ref pairs to timestamps provided by this + result</doc> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="CollectionRef"/> + <type name="guint64"/> + </type> + </parameter> + <parameter name="summary_last_modified" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="441">Unix timestamp (seconds since the epoch, UTC) when + the summary file for the result was last modified, or `0` if this is unknown</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + </parameters> + </constructor> + <method name="compare" + c:identifier="ostree_repo_finder_result_compare" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="494">Compare two #OstreeRepoFinderResult instances to work out which one is better +to pull from, and hence needs to be ordered before the other.</doc> + <source-position filename="ostree-repo-finder.h" line="164"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="502"><0 if @a is ordered before @b, 0 if they are ordered equally, + >0 if @b is ordered before @a</doc> + <type name="gint" c:type="gint"/> + </return-value> + <parameters> + <instance-parameter name="a" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="496">an #OstreeRepoFinderResult</doc> + <type name="RepoFinderResult" + c:type="const OstreeRepoFinderResult*"/> + </instance-parameter> + <parameter name="b" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="497">an #OstreeRepoFinderResult</doc> + <type name="RepoFinderResult" + c:type="const OstreeRepoFinderResult*"/> + </parameter> + </parameters> + </method> + <method name="dup" + c:identifier="ostree_repo_finder_result_dup" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="475">Copy an #OstreeRepoFinderResult.</doc> + <source-position filename="ostree-repo-finder.h" line="162"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="481">a newly allocated copy of @result</doc> + <type name="RepoFinderResult" c:type="OstreeRepoFinderResult*"/> + </return-value> + <parameters> + <instance-parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="477">an #OstreeRepoFinderResult to copy</doc> + <type name="RepoFinderResult" c:type="OstreeRepoFinderResult*"/> + </instance-parameter> + </parameters> + </method> + <method name="free" + c:identifier="ostree_repo_finder_result_free" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="545">Free the given @result.</doc> + <source-position filename="ostree-repo-finder.h" line="167"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="result" transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="547">an #OstreeRepoFinderResult</doc> + <type name="RepoFinderResult" c:type="OstreeRepoFinderResult*"/> + </instance-parameter> + </parameters> + </method> + <function name="freev" + c:identifier="ostree_repo_finder_result_freev" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="567">Free the given @results array, freeing each element and the container.</doc> + <source-position filename="ostree-repo-finder.h" line="184"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="results" transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="569">an #OstreeRepoFinderResult</doc> + <array c:type="OstreeRepoFinderResult**"> + <type name="RepoFinderResult" c:type="OstreeRepoFinderResult*"/> + </array> + </parameter> + </parameters> + </function> + </record> + <record name="RepoImportArchiveOptions" + c:type="OstreeRepoImportArchiveOptions" + introspectable="0"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="807">An extensible options structure controlling archive import. Ensure that +you have entirely zeroed the structure, then set just the desired +options. This is used by ostree_repo_import_archive_to_mtree().</doc> + <source-position filename="ostree-repo.h" line="825"/> + <field name="ignore_unsupported_content" writable="1" bits="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="autocreate_parents" writable="1" bits="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="use_ostree_convention" writable="1" bits="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="callback_with_entry_pathname" writable="1" bits="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="reserved" writable="1" bits="28"> + <type name="guint" c:type="guint"/> + </field> + <field name="unused_uint" writable="1"> + <array zero-terminated="0" fixed-size="8"> + <type name="guint" c:type="guint"/> + </array> + </field> + <field name="translate_pathname" writable="1"> + <type name="RepoImportArchiveTranslatePathname" + c:type="OstreeRepoImportArchiveTranslatePathname"/> + </field> + <field name="translate_pathname_user_data" writable="1"> + <type name="gpointer" c:type="gpointer"/> + </field> + <field name="unused_ptrs" writable="1"> + <array zero-terminated="0" fixed-size="6"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <callback name="RepoImportArchiveTranslatePathname" + c:type="OstreeRepoImportArchiveTranslatePathname" + version="2017.11"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="782">Possibly change a pathname while importing an archive. If %NULL is returned, +then @src_path will be used unchanged. Otherwise, return a new pathname which +will be freed via `g_free()`. + +This pathname translation will be performed *before* any processing from an +active `OstreeRepoCommitModifier`. Will be invoked for all directory and file +types, first with outer directories, then their sub-files and directories. + +Note that enabling pathname translation will always override the setting for +`use_ostree_convention`.</doc> + <source-position filename="ostree-repo.h" line="802"/> + <return-value transfer-ownership="full"> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="784">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="stbuf" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="785">Stat buffer</doc> + <type name="gpointer" c:type="const stat*"/> + </parameter> + <parameter name="src_path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="786">Path in the archive</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1" + closure="3"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="787">User data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </callback> + <bitfield name="RepoListObjectsFlags" c:type="OstreeRepoListObjectsFlags"> + <source-position filename="ostree-repo.h" line="1053"/> + <member name="loose" + value="1" + c:identifier="OSTREE_REPO_LIST_OBJECTS_LOOSE"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1043">List only loose (plain file) objects</doc> + </member> + <member name="packed" + value="2" + c:identifier="OSTREE_REPO_LIST_OBJECTS_PACKED"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1044">List only packed (compacted into blobs) objects</doc> + </member> + <member name="all" value="4" c:identifier="OSTREE_REPO_LIST_OBJECTS_ALL"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1045">List all objects</doc> + </member> + <member name="no_parents" + value="8" + c:identifier="OSTREE_REPO_LIST_OBJECTS_NO_PARENTS"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1046">Only list objects in this repo, not parents</doc> + </member> + </bitfield> + <bitfield name="RepoListRefsExtFlags" c:type="OstreeRepoListRefsExtFlags"> + <source-position filename="ostree-repo.h" line="549"/> + <member name="none" + value="0" + c:identifier="OSTREE_REPO_LIST_REFS_EXT_NONE"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="539">No flags.</doc> + </member> + <member name="aliases" + value="1" + c:identifier="OSTREE_REPO_LIST_REFS_EXT_ALIASES"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="540">Only list aliases. Since: 2017.10</doc> + </member> + <member name="exclude_remotes" + value="2" + c:identifier="OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_REMOTES"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="541">Exclude remote refs. Since: 2017.11</doc> + </member> + <member name="exclude_mirrors" + value="4" + c:identifier="OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_MIRRORS"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="542">Exclude mirrored refs. Since: 2019.2</doc> + </member> + </bitfield> + <enumeration name="RepoLockType" + version="2021.3" + c:type="OstreeRepoLockType"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1588">Flags controlling repository locking.</doc> + <source-position filename="ostree-repo.h" line="1600"/> + <member name="shared" value="0" c:identifier="OSTREE_REPO_LOCK_SHARED"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1590">A "read only" lock; multiple readers are allowed.</doc> + </member> + <member name="exclusive" + value="1" + c:identifier="OSTREE_REPO_LOCK_EXCLUSIVE"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1591">A writable lock at most one writer can be active, and zero readers.</doc> + </member> + </enumeration> + <enumeration name="RepoMode" c:type="OstreeRepoMode"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="189">See the documentation of #OstreeRepo for more information about the +possible modes.</doc> + <source-position filename="ostree-core.h" line="208"/> + <member name="bare" value="0" c:identifier="OSTREE_REPO_MODE_BARE"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="191">Files are stored as themselves; checkouts are hardlinks; can only be written as root</doc> + </member> + <member name="archive" value="1" c:identifier="OSTREE_REPO_MODE_ARCHIVE"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="192">Files are compressed, should be owned by non-root. Can be served via HTTP. Since: 2017.12</doc> + </member> + <member name="archive_z2" + value="1" + c:identifier="OSTREE_REPO_MODE_ARCHIVE_Z2"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="193">Legacy alias for `OSTREE_REPO_MODE_ARCHIVE`</doc> + </member> + <member name="bare_user" + value="2" + c:identifier="OSTREE_REPO_MODE_BARE_USER"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="194">Files are stored as themselves, except ownership; can be written by user. Hardlinks work only in user checkouts.</doc> + </member> + <member name="bare_user_only" + value="3" + c:identifier="OSTREE_REPO_MODE_BARE_USER_ONLY"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="195">Same as BARE_USER, but all metadata is not stored, so it can only be used for user checkouts. Does not need xattrs.</doc> + </member> + <member name="bare_split_xattrs" + value="4" + c:identifier="OSTREE_REPO_MODE_BARE_SPLIT_XATTRS"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="196">Same as BARE_USER, but xattrs are stored separately from file content, with dedicated object types.</doc> + </member> + </enumeration> + <bitfield name="RepoPruneFlags" c:type="OstreeRepoPruneFlags"> + <source-position filename="ostree-repo.h" line="1272"/> + <member name="none" + value="0" + c:identifier="OSTREE_REPO_PRUNE_FLAGS_NONE"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1262">No special options for pruning</doc> + </member> + <member name="no_prune" + value="1" + c:identifier="OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1263">Don't actually delete objects</doc> + </member> + <member name="refs_only" + value="2" + c:identifier="OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1264">Do not traverse individual commit objects, only follow refs</doc> + </member> + <member name="commit_only" + value="4" + c:identifier="OSTREE_REPO_PRUNE_FLAGS_COMMIT_ONLY"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1265">Only traverse commit objects. (Since 2022.2)</doc> + </member> + </bitfield> + <record name="RepoPruneOptions" c:type="OstreeRepoPruneOptions"> + <source-position filename="ostree-repo.h" line="1300"/> + <field name="flags" writable="1"> + <type name="RepoPruneFlags" c:type="OstreeRepoPruneFlags"/> + </field> + <field name="reachable" writable="1"> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </field> + <field name="unused_bools" writable="1"> + <array zero-terminated="0" fixed-size="6"> + <type name="gboolean" c:type="gboolean"/> + </array> + </field> + <field name="unused_ints" writable="1"> + <array zero-terminated="0" fixed-size="6"> + <type name="gint" c:type="int"/> + </array> + </field> + <field name="unused_ptrs" writable="1"> + <array zero-terminated="0" fixed-size="7"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <bitfield name="RepoPullFlags" c:type="OstreeRepoPullFlags"> + <source-position filename="ostree-repo.h" line="1337"/> + <member name="none" value="0" c:identifier="OSTREE_REPO_PULL_FLAGS_NONE"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1323">No special options for pull</doc> + </member> + <member name="mirror" + value="1" + c:identifier="OSTREE_REPO_PULL_FLAGS_MIRROR"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1324">Write out refs suitable for mirrors and fetch all refs if none requested</doc> + </member> + <member name="commit_only" + value="2" + c:identifier="OSTREE_REPO_PULL_FLAGS_COMMIT_ONLY"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1325">Fetch only the commit metadata</doc> + </member> + <member name="untrusted" + value="4" + c:identifier="OSTREE_REPO_PULL_FLAGS_UNTRUSTED"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1326">Do verify checksums of local (filesystem-accessible) repositories (defaults on for HTTP)</doc> + </member> + <member name="bareuseronly_files" + value="8" + c:identifier="OSTREE_REPO_PULL_FLAGS_BAREUSERONLY_FILES"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1327">Since 2017.7. Reject writes of content objects with modes outside of 0775.</doc> + </member> + <member name="trusted_http" + value="16" + c:identifier="OSTREE_REPO_PULL_FLAGS_TRUSTED_HTTP"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1328">Don't verify checksums of objects HTTP repositories (Since: 2017.12)</doc> + </member> + </bitfield> + <enumeration name="RepoRemoteChange" c:type="OstreeRepoRemoteChange"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="164">The remote change operation.</doc> + <source-position filename="ostree-repo.h" line="179"/> + <member name="add" + value="0" + c:identifier="OSTREE_REPO_REMOTE_CHANGE_ADD"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="167">Add a remote</doc> + </member> + <member name="add_if_not_exists" + value="1" + c:identifier="OSTREE_REPO_REMOTE_CHANGE_ADD_IF_NOT_EXISTS"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="168">Like above, but do nothing if the remote exists</doc> + </member> + <member name="delete" + value="2" + c:identifier="OSTREE_REPO_REMOTE_CHANGE_DELETE"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="169">Delete a remote</doc> + </member> + <member name="delete_if_exists" + value="3" + c:identifier="OSTREE_REPO_REMOTE_CHANGE_DELETE_IF_EXISTS"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="170">Delete a remote, do nothing if the remote does not exist</doc> + </member> + <member name="replace" + value="4" + c:identifier="OSTREE_REPO_REMOTE_CHANGE_REPLACE"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="171">Add or replace a remote (Since: 2019.2)</doc> + </member> + </enumeration> + <bitfield name="RepoResolveRevExtFlags" + c:type="OstreeRepoResolveRevExtFlags"> + <source-position filename="ostree-repo.h" line="511"/> + <member name="none" + value="0" + c:identifier="OSTREE_REPO_RESOLVE_REV_EXT_NONE"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="505">No flags.</doc> + </member> + <member name="local_only" + value="1" + c:identifier="OSTREE_REPO_RESOLVE_REV_EXT_LOCAL_ONLY"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="506">Exclude remote and mirrored refs. Since: 2019.2</doc> + </member> + </bitfield> + <record name="RepoTransactionStats" + c:type="OstreeRepoTransactionStats" + glib:type-name="OstreeRepoTransactionStats" + glib:get-type="ostree_repo_transaction_stats_get_type" + c:symbol-prefix="repo_transaction_stats"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="270">A list of statistics for each transaction that may be +interesting for reporting purposes.</doc> + <source-position filename="ostree-repo.h" line="304"/> + <field name="metadata_objects_total" writable="1"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="272">The total number of metadata objects +in the repository after this transaction has completed.</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="metadata_objects_written" writable="1"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="274">The number of metadata objects that +were written to the repository in this transaction.</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="content_objects_total" writable="1"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="276">The total number of content objects +in the repository after this transaction has completed.</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="content_objects_written" writable="1"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="278">The number of content objects that +were written to the repository in this transaction.</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="content_bytes_written" writable="1"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="280">The amount of data added to the repository, +in bytes, counting only content objects.</doc> + <type name="guint64" c:type="guint64"/> + </field> + <field name="devino_cache_hits" writable="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="padding1" writable="1"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="282">reserved</doc> + <type name="guint" c:type="guint"/> + </field> + <field name="padding2" writable="1"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="283">reserved</doc> + <type name="guint64" c:type="guint64"/> + </field> + <field name="padding3" writable="1"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="284">reserved</doc> + <type name="guint64" c:type="guint64"/> + </field> + <field name="padding4" writable="1"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="285">reserved</doc> + <type name="guint64" c:type="guint64"/> + </field> + </record> + <bitfield name="RepoVerifyFlags" + version="2021.4" + c:type="OstreeRepoVerifyFlags"> + <source-position filename="ostree-repo.h" line="1570"/> + <member name="none" + value="0" + c:identifier="OSTREE_REPO_VERIFY_FLAGS_NONE"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1560">No flags</doc> + </member> + <member name="no_gpg" + value="1" + c:identifier="OSTREE_REPO_VERIFY_FLAGS_NO_GPG"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1561">Skip GPG verification</doc> + </member> + <member name="no_signapi" + value="2" + c:identifier="OSTREE_REPO_VERIFY_FLAGS_NO_SIGNAPI"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1562">Skip all other signature verification methods</doc> + </member> + </bitfield> + <record name="RollsumMatches" c:type="OstreeRollsumMatches"> + <source-position filename="ostree-rollsum.h" line="35"/> + <field name="from_rollsums" writable="1"> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </field> + <field name="to_rollsums" writable="1"> + <type name="GLib.HashTable" c:type="GHashTable*"> + <type name="gpointer" c:type="gpointer"/> + <type name="gpointer" c:type="gpointer"/> + </type> + </field> + <field name="crcmatches" writable="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="bufmatches" writable="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="total" writable="1"> + <type name="guint" c:type="guint"/> + </field> + <field name="match_size" writable="1"> + <type name="guint64" c:type="guint64"/> + </field> + <field name="matches" writable="1"> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <function-macro name="SEPOLICY" + c:identifier="OSTREE_SEPOLICY" + introspectable="0"> + <source-position filename="ostree-sepolicy.h" line="27"/> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <constant name="SHA256_DIGEST_LEN" + value="32" + c:type="OSTREE_SHA256_DIGEST_LEN"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="47">Length of a sha256 digest when expressed as raw bytes</doc> + <source-position filename="ostree-core.h" line="52"/> + <type name="gint" c:type="gint"/> + </constant> + <constant name="SHA256_STRING_LEN" + value="64" + c:type="OSTREE_SHA256_STRING_LEN"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="54">Length of a sha256 digest when expressed as a hexadecimal string</doc> + <source-position filename="ostree-core.h" line="59"/> + <type name="gint" c:type="gint"/> + </constant> + <constant name="SIGN_NAME_ED25519" + value="ed25519" + c:type="OSTREE_SIGN_NAME_ED25519" + version="2020.4"> + <doc xml:space="preserve" + filename="ostree-sign.h" + line="50">The name of the default ed25519 signing type.</doc> + <source-position filename="ostree-sign.h" line="56"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="SUMMARY_GVARIANT_STRING" + value="(a(s(taya{sv}))a{sv})" + c:type="OSTREE_SUMMARY_GVARIANT_STRING"> + <source-position filename="ostree-core.h" line="174"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="SUMMARY_SIG_GVARIANT_STRING" + value="a{sv}" + c:type="OSTREE_SUMMARY_SIG_GVARIANT_STRING"> + <source-position filename="ostree-core.h" line="177"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <function-macro name="SYSROOT" + c:identifier="OSTREE_SYSROOT" + introspectable="0"> + <source-position filename="ostree-sysroot.h" line="36"/> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <function-macro name="SYSROOT_UPGRADER" + c:identifier="OSTREE_SYSROOT_UPGRADER" + introspectable="0"> + <source-position filename="ostree-sysroot-upgrader.h" line="27"/> + <parameters> + <parameter name="obj"> + </parameter> + </parameters> + </function-macro> + <class name="SePolicy" + c:symbol-prefix="sepolicy" + c:type="OstreeSePolicy" + parent="GObject.Object" + glib:type-name="OstreeSePolicy" + glib:get-type="ostree_sepolicy_get_type"> + <implements name="Gio.Initable"/> + <constructor name="new" c:identifier="ostree_sepolicy_new" throws="1"> + <source-position filename="ostree-sepolicy.h" line="36"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="469">An accessor object for SELinux policy in root located at @path</doc> + <type name="SePolicy" c:type="OstreeSePolicy*"/> + </return-value> + <parameters> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="465">Path to a root directory</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="466">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_at" + c:identifier="ostree_sepolicy_new_at" + version="2017.4" + throws="1"> + <source-position filename="ostree-sepolicy.h" line="41"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="485">An accessor object for SELinux policy in root located at @rootfs_dfd</doc> + <type name="SePolicy" c:type="OstreeSePolicy*"/> + </return-value> + <parameters> + <parameter name="rootfs_dfd" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="481">Directory fd for rootfs (will not be cloned)</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="482">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_from_commit" + c:identifier="ostree_sepolicy_new_from_commit" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="271">Extract the SELinux policy from a commit object via a partial checkout. This is useful +for labeling derived content as separate commits. + +This function is the backend of `ostree_repo_commit_modifier_set_sepolicy_from_commit()`.</doc> + <source-position filename="ostree-sepolicy.h" line="46"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="283">A new policy</doc> + <type name="SePolicy" c:type="OstreeSePolicy*"/> + </return-value> + <parameters> + <parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="273">The repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="rev" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="274">ostree ref or checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="275">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </constructor> + <function name="fscreatecon_cleanup" + c:identifier="ostree_sepolicy_fscreatecon_cleanup"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="710">Cleanup function for ostree_sepolicy_setfscreatecon().</doc> + <source-position filename="ostree-sepolicy.h" line="91"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="unused" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="712">Not used, just in case you didn't infer that from the parameter name</doc> + <type name="gpointer" c:type="void**"/> + </parameter> + </parameters> + </function> + <method name="get_csum" + c:identifier="ostree_sepolicy_get_csum" + version="2016.5"> + <source-position filename="ostree-sepolicy.h" line="58"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="533">Checksum of current policy</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="SePolicy" c:type="OstreeSePolicy*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_label" + c:identifier="ostree_sepolicy_get_label" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="547">Store in @out_label the security context for the given @relpath and +mode @unix_mode. If the policy does not specify a label, %NULL +will be returned.</doc> + <source-position filename="ostree-sepolicy.h" line="61"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="549">Self</doc> + <type name="SePolicy" c:type="OstreeSePolicy*"/> + </instance-parameter> + <parameter name="relpath" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="550">Path</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="unix_mode" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="551">Unix mode</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + <parameter name="out_label" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="552">Return location for security context</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="553">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="get_name" c:identifier="ostree_sepolicy_get_name"> + <source-position filename="ostree-sepolicy.h" line="55"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="517">Type of current policy</doc> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="SePolicy" c:type="OstreeSePolicy*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_path" c:identifier="ostree_sepolicy_get_path"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="497">This API should be considered deprecated, because it's supported for +policy objects to be created from file-descriptor relative paths, which +may not be globally accessible.</doc> + <source-position filename="ostree-sepolicy.h" line="52"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="505">Path to rootfs</doc> + <type name="Gio.File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="499">A SePolicy object</doc> + <type name="SePolicy" c:type="OstreeSePolicy*"/> + </instance-parameter> + </parameters> + </method> + <method name="restorecon" + c:identifier="ostree_sepolicy_restorecon" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="599">Reset the security context of @target based on the SELinux policy.</doc> + <source-position filename="ostree-sepolicy.h" line="75"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="601">Self</doc> + <type name="SePolicy" c:type="OstreeSePolicy*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="602">Path string to use for policy lookup</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="info" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="603">File attributes</doc> + <type name="Gio.FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="target" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="604">Physical path to target file</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="605">Flags controlling behavior</doc> + <type name="SePolicyRestoreconFlags" + c:type="OstreeSePolicyRestoreconFlags"/> + </parameter> + <parameter name="out_new_label" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="606">New label, or %NULL if unchanged</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="607">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="setfscreatecon" + c:identifier="ostree_sepolicy_setfscreatecon" + throws="1"> + <source-position filename="ostree-sepolicy.h" line="85"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="676">Policy</doc> + <type name="SePolicy" c:type="OstreeSePolicy*"/> + </instance-parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="677">Use this path to determine a label</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="678">Used along with @path</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + </parameters> + </method> + <property name="path" + writable="1" + construct-only="1" + transfer-ownership="none"> + <type name="Gio.File"/> + </property> + <property name="rootfs-dfd" + writable="1" + construct-only="1" + transfer-ownership="none"> + <type name="gint" c:type="gint"/> + </property> + </class> + <bitfield name="SePolicyRestoreconFlags" + c:type="OstreeSePolicyRestoreconFlags"> + <source-position filename="ostree-sepolicy.h" line="72"/> + <member name="none" + value="0" + c:identifier="OSTREE_SEPOLICY_RESTORECON_FLAGS_NONE"> + </member> + <member name="allow_nolabel" + value="1" + c:identifier="OSTREE_SEPOLICY_RESTORECON_FLAGS_ALLOW_NOLABEL"> + </member> + <member name="keep_existing" + value="2" + c:identifier="OSTREE_SEPOLICY_RESTORECON_FLAGS_KEEP_EXISTING"> + </member> + </bitfield> + <interface name="Sign" + c:symbol-prefix="sign" + c:type="OstreeSign" + glib:type-name="OstreeSign" + glib:get-type="ostree_sign_get_type" + glib:type-struct="SignInterface"> + <source-position filename="ostree-sign.h" line="93"/> + <function name="get_all" + c:identifier="ostree_sign_get_all" + version="2020.2"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="518">Return an array with newly allocated instances of all available +signing engines; they will not be initialized.</doc> + <source-position filename="ostree-sign.h" line="159"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="524">an array of signing engines</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="Sign"/> + </array> + </return-value> + </function> + <function name="get_by_name" + c:identifier="ostree_sign_get_by_name" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="542">Create a new instance of a signing engine.</doc> + <source-position filename="ostree-sign.h" line="162"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="549">New signing engine, or %NULL if the engine is not known</doc> + <type name="Sign" c:type="OstreeSign*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="544">the name of desired signature engine</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <virtual-method name="add_pk" + invoker="add_pk" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="201">Add the public key for verification. Could be called multiple times for +adding all needed keys to be used for verification. + +The @public_key argument depends of the particular engine implementation.</doc> + <source-position filename="ostree-sign.h" line="87"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="212">@TRUE in case if the key could be added successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="203">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="public_key" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="204">single public key to be added</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="clear_keys" + invoker="clear_keys" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="124">Clear all previously preloaded secret and public keys.</doc> + <source-position filename="ostree-sign.h" line="79"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="131">@TRUE in case if no errors, @FALSE in case of error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="126">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="data" invoker="data" version="2020.2" throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="268">Sign the given @data with pre-loaded secret key. + +Depending of the signing engine used you will need to load +the secret key with #ostree_sign_set_sk.</doc> + <source-position filename="ostree-sign.h" line="67"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="281">@TRUE if @data has been signed successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="270">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="271">the raw data to be signed with pre-loaded secret key</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="signature" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="272">in case of success will contain signature</doc> + <type name="GLib.Bytes" c:type="GBytes**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="273">A #GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="data_verify" + invoker="data_verify" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="301">Verify given data against signatures with pre-loaded public keys. + +Depending of the signing engine used you will need to load +the public key(s) with #ostree_sign_set_pk, #ostree_sign_add_pk +or #ostree_sign_load_pk.</doc> + <source-position filename="ostree-sign.h" line="72"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="315">@TRUE if @data has been signed at least with any single valid key, +@FALSE in case of error or no valid keys are available (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="303">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="304">the raw data to check</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="signatures" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="305">the signatures to be checked</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="out_success_message" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="306">success message returned by the signing engine</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="get_name" invoker="get_name" version="2020.2"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="436">Return the pointer to the name of currently used/selected signing engine.</doc> + <source-position filename="ostree-sign.h" line="66"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="442">pointer to the name +@NULL in case of error (unlikely).</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="438">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="load_pk" + invoker="load_pk" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="229">Load public keys for verification from anywhere. +It is expected that all keys would be added to already pre-loaded keys. + +The @options argument depends of the particular engine implementation. + +For example, @ed25515 engine could use following string-formatted options: +- @filename -- single file to use to load keys from +- @basedir -- directory containing subdirectories + 'trusted.ed25519.d' and 'revoked.ed25519.d' with appropriate + public keys. Used for testing and re-definition of system-wide + directories if defaults are not suitable for any reason.</doc> + <source-position filename="ostree-sign.h" line="90"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="247">@TRUE in case if at least one key could be load successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="231">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="options" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="232">any options</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="metadata_format" + invoker="metadata_format" + version="2020.2"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="104">Return the pointer to the string with format used in (detached) metadata for +current signing engine.</doc> + <source-position filename="ostree-sign.h" line="78"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="111">pointer to the metadata format, +@NULL in case of error (unlikely).</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="106">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="metadata_key" + invoker="metadata_key" + version="2020.2"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="84">Return the pointer to the name of the key used in (detached) metadata for +current signing engine.</doc> + <source-position filename="ostree-sign.h" line="77"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="91">pointer to the metadata key name, +@NULL in case of error (unlikely).</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="86">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + </parameters> + </virtual-method> + <virtual-method name="set_pk" + invoker="set_pk" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="173">Set the public key for verification. It is expected what all +previously pre-loaded public keys will be dropped. + +The @public_key argument depends of the particular engine implementation.</doc> + <source-position filename="ostree-sign.h" line="84"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="184">@TRUE in case if the key could be set successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="175">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="public_key" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="176">single public key to be added</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <virtual-method name="set_sk" + invoker="set_sk" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="146">Set the secret key to be used for signing data, commits and summary. + +The @secret_key argument depends of the particular engine implementation.</doc> + <source-position filename="ostree-sign.h" line="81"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="156">@TRUE in case if the key could be set successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="148">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="secret_key" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="149">secret key to be added</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </virtual-method> + <method name="add_pk" + c:identifier="ostree_sign_add_pk" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="201">Add the public key for verification. Could be called multiple times for +adding all needed keys to be used for verification. + +The @public_key argument depends of the particular engine implementation.</doc> + <source-position filename="ostree-sign.h" line="148"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="212">@TRUE in case if the key could be added successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="203">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="public_key" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="204">single public key to be added</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="clear_keys" + c:identifier="ostree_sign_clear_keys" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="124">Clear all previously preloaded secret and public keys.</doc> + <source-position filename="ostree-sign.h" line="134"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="131">@TRUE in case if no errors, @FALSE in case of error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="126">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + </parameters> + </method> + <method name="commit" + c:identifier="ostree_sign_commit" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="456">Add a signature to a commit. + +Depending of the signing engine used you will need to load +the secret key with #ostree_sign_set_sk.</doc> + <source-position filename="ostree-sign.h" line="119"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="469">@TRUE if commit has been signed successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="458">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="459">an #OsreeRepo object</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="commit_checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="460">SHA256 of given commit to sign</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="461">A #GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="commit_verify" + c:identifier="ostree_sign_commit_verify" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="369">Verify if commit is signed with known key. + +Depending of the signing engine used you will need to load +the public key(s) for verification with #ostree_sign_set_pk, +#ostree_sign_add_pk and/or #ostree_sign_load_pk.</doc> + <source-position filename="ostree-sign.h" line="126"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="384">@TRUE if commit has been verified successfully, +@FALSE in case of error or no valid keys are available (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="371">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="372">an #OsreeRepo object</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="commit_checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="373">SHA256 of given commit to verify</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + <parameter name="out_success_message" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="374">success message returned by the signing engine</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="375">A #GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="data" + c:identifier="ostree_sign_data" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="268">Sign the given @data with pre-loaded secret key. + +Depending of the signing engine used you will need to load +the secret key with #ostree_sign_set_sk.</doc> + <source-position filename="ostree-sign.h" line="99"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="281">@TRUE if @data has been signed successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="270">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="271">the raw data to be signed with pre-loaded secret key</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="signature" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="272">in case of success will contain signature</doc> + <type name="GLib.Bytes" c:type="GBytes**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="273">A #GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="data_verify" + c:identifier="ostree_sign_data_verify" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="301">Verify given data against signatures with pre-loaded public keys. + +Depending of the signing engine used you will need to load +the public key(s) with #ostree_sign_set_pk, #ostree_sign_add_pk +or #ostree_sign_load_pk.</doc> + <source-position filename="ostree-sign.h" line="106"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="315">@TRUE if @data has been signed at least with any single valid key, +@FALSE in case of error or no valid keys are available (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="303">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="304">the raw data to check</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="signatures" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="305">the signatures to be checked</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="out_success_message" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="306">success message returned by the signing engine</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="dummy_add_pk" + c:identifier="ostree_sign_dummy_add_pk" + throws="1"> + <source-position filename="ostree-sign-dummy.h" line="72"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="dummy_data" + c:identifier="ostree_sign_dummy_data" + throws="1"> + <source-position filename="ostree-sign-dummy.h" line="55"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="signature" transfer-ownership="none"> + <type name="GLib.Bytes" c:type="GBytes**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="dummy_data_verify" + c:identifier="ostree_sign_dummy_data_verify" + throws="1"> + <source-position filename="ostree-sign-dummy.h" line="61"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="signatures" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="success_message" transfer-ownership="none"> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="dummy_get_name" c:identifier="ostree_sign_dummy_get_name"> + <source-position filename="ostree-sign-dummy.h" line="53"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + </parameters> + </method> + <method name="dummy_metadata_format" + c:identifier="ostree_sign_dummy_metadata_format"> + <source-position filename="ostree-sign-dummy.h" line="68"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + </parameters> + </method> + <method name="dummy_metadata_key" + c:identifier="ostree_sign_dummy_metadata_key"> + <source-position filename="ostree-sign-dummy.h" line="67"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + </parameters> + </method> + <method name="dummy_set_pk" + c:identifier="ostree_sign_dummy_set_pk" + throws="1"> + <source-position filename="ostree-sign-dummy.h" line="71"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="dummy_set_sk" + c:identifier="ostree_sign_dummy_set_sk" + throws="1"> + <source-position filename="ostree-sign-dummy.h" line="70"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="key" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="ed25519_add_pk" + c:identifier="ostree_sign_ed25519_add_pk" + throws="1"> + <source-position filename="ostree-sign-ed25519.h" line="80"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="public_key" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="ed25519_clear_keys" + c:identifier="ostree_sign_ed25519_clear_keys" + throws="1"> + <source-position filename="ostree-sign-ed25519.h" line="69"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + </parameters> + </method> + <method name="ed25519_data" + c:identifier="ostree_sign_ed25519_data" + throws="1"> + <source-position filename="ostree-sign-ed25519.h" line="53"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="signature" transfer-ownership="none"> + <type name="GLib.Bytes" c:type="GBytes**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="ed25519_data_verify" + c:identifier="ostree_sign_ed25519_data_verify" + throws="1"> + <source-position filename="ostree-sign-ed25519.h" line="59"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="data" transfer-ownership="none"> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="signatures" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="out_success_message" transfer-ownership="none"> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </method> + <method name="ed25519_get_name" + c:identifier="ostree_sign_ed25519_get_name"> + <source-position filename="ostree-sign-ed25519.h" line="65"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + </parameters> + </method> + <method name="ed25519_load_pk" + c:identifier="ostree_sign_ed25519_load_pk" + throws="1"> + <source-position filename="ostree-sign-ed25519.h" line="84"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="options" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="ed25519_metadata_format" + c:identifier="ostree_sign_ed25519_metadata_format"> + <source-position filename="ostree-sign-ed25519.h" line="67"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + </parameters> + </method> + <method name="ed25519_metadata_key" + c:identifier="ostree_sign_ed25519_metadata_key"> + <source-position filename="ostree-sign-ed25519.h" line="66"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + </parameters> + </method> + <method name="ed25519_set_pk" + c:identifier="ostree_sign_ed25519_set_pk" + throws="1"> + <source-position filename="ostree-sign-ed25519.h" line="76"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="public_key" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="ed25519_set_sk" + c:identifier="ostree_sign_ed25519_set_sk" + throws="1"> + <source-position filename="ostree-sign-ed25519.h" line="72"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="secret_key" transfer-ownership="none"> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="get_name" + c:identifier="ostree_sign_get_name" + version="2020.2"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="436">Return the pointer to the name of currently used/selected signing engine.</doc> + <source-position filename="ostree-sign.h" line="96"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="442">pointer to the name +@NULL in case of error (unlikely).</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="438">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + </parameters> + </method> + <method name="load_pk" + c:identifier="ostree_sign_load_pk" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="229">Load public keys for verification from anywhere. +It is expected that all keys would be added to already pre-loaded keys. + +The @options argument depends of the particular engine implementation. + +For example, @ed25515 engine could use following string-formatted options: +- @filename -- single file to use to load keys from +- @basedir -- directory containing subdirectories + 'trusted.ed25519.d' and 'revoked.ed25519.d' with appropriate + public keys. Used for testing and re-definition of system-wide + directories if defaults are not suitable for any reason.</doc> + <source-position filename="ostree-sign.h" line="153"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="247">@TRUE in case if at least one key could be load successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="231">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="options" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="232">any options</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="metadata_format" + c:identifier="ostree_sign_metadata_format" + version="2020.2"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="104">Return the pointer to the string with format used in (detached) metadata for +current signing engine.</doc> + <source-position filename="ostree-sign.h" line="116"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="111">pointer to the metadata format, +@NULL in case of error (unlikely).</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="106">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + </parameters> + </method> + <method name="metadata_key" + c:identifier="ostree_sign_metadata_key" + version="2020.2"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="84">Return the pointer to the name of the key used in (detached) metadata for +current signing engine.</doc> + <source-position filename="ostree-sign.h" line="113"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="91">pointer to the metadata key name, +@NULL in case of error (unlikely).</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="86">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_pk" + c:identifier="ostree_sign_set_pk" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="173">Set the public key for verification. It is expected what all +previously pre-loaded public keys will be dropped. + +The @public_key argument depends of the particular engine implementation.</doc> + <source-position filename="ostree-sign.h" line="143"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="184">@TRUE in case if the key could be set successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="175">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="public_key" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="176">single public key to be added</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="set_sk" + c:identifier="ostree_sign_set_sk" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="146">Set the secret key to be used for signing data, commits and summary. + +The @secret_key argument depends of the particular engine implementation.</doc> + <source-position filename="ostree-sign.h" line="138"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="156">@TRUE in case if the key could be set successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="148">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="secret_key" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="149">secret key to be added</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </method> + <method name="summary" + c:identifier="ostree_sign_summary" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="584">Add a signature to a summary file. +Based on ostree_repo_add_gpg_signature_summary implementation.</doc> + <source-position filename="ostree-sign.h" line="165"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="595">@TRUE if summary file has been signed with all provided keys</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="586">Self</doc> + <type name="Sign" c:type="OstreeSign*"/> + </instance-parameter> + <parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="587">ostree repository</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="keys" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="588">keys -- GVariant containing keys as GVarints specific to signature type.</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="589">A #GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + </interface> + <record name="SignDummy" c:type="OstreeSignDummy" disguised="1"> + <source-position filename="ostree-sign-dummy.h" line="36"/> + </record> + <record name="SignDummyClass" c:type="OstreeSignDummyClass"> + <source-position filename="ostree-sign-dummy.h" line="37"/> + <field name="parent_class" writable="1"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <record name="SignEd25519" c:type="OstreeSignEd25519" disguised="1"> + <source-position filename="ostree-sign-ed25519.h" line="36"/> + </record> + <record name="SignEd25519Class" c:type="OstreeSignEd25519Class"> + <source-position filename="ostree-sign-ed25519.h" line="37"/> + <field name="parent_class" writable="1"> + <type name="GObject.ObjectClass" c:type="GObjectClass"/> + </field> + </record> + <record name="SignInterface" + c:type="OstreeSignInterface" + glib:is-gtype-struct-for="Sign"> + <source-position filename="ostree-sign.h" line="93"/> + <field name="g_iface"> + <type name="GObject.TypeInterface" c:type="GTypeInterface"/> + </field> + <field name="get_name"> + <callback name="get_name"> + <source-position filename="ostree-sign.h" line="66"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="442">pointer to the name +@NULL in case of error (unlikely).</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="438">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="data"> + <callback name="data" throws="1"> + <source-position filename="ostree-sign.h" line="67"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="281">@TRUE if @data has been signed successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="270">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="271">the raw data to be signed with pre-loaded secret key</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="signature" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="272">in case of success will contain signature</doc> + <type name="GLib.Bytes" c:type="GBytes**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="273">A #GCancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="data_verify"> + <callback name="data_verify" throws="1"> + <source-position filename="ostree-sign.h" line="72"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="315">@TRUE if @data has been signed at least with any single valid key, +@FALSE in case of error or no valid keys are available (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="303">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </parameter> + <parameter name="data" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="304">the raw data to check</doc> + <type name="GLib.Bytes" c:type="GBytes*"/> + </parameter> + <parameter name="signatures" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="305">the signatures to be checked</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="out_success_message" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="306">success message returned by the signing engine</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </callback> + </field> + <field name="metadata_key"> + <callback name="metadata_key"> + <source-position filename="ostree-sign.h" line="77"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="91">pointer to the metadata key name, +@NULL in case of error (unlikely).</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="86">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="metadata_format"> + <callback name="metadata_format"> + <source-position filename="ostree-sign.h" line="78"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="111">pointer to the metadata format, +@NULL in case of error (unlikely).</doc> + <type name="utf8" c:type="const gchar*"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="106">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="clear_keys"> + <callback name="clear_keys" throws="1"> + <source-position filename="ostree-sign.h" line="79"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="131">@TRUE in case if no errors, @FALSE in case of error</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="126">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="set_sk"> + <callback name="set_sk" throws="1"> + <source-position filename="ostree-sign.h" line="81"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="156">@TRUE in case if the key could be set successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="148">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </parameter> + <parameter name="secret_key" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="149">secret key to be added</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="set_pk"> + <callback name="set_pk" throws="1"> + <source-position filename="ostree-sign.h" line="84"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="184">@TRUE in case if the key could be set successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="175">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </parameter> + <parameter name="public_key" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="176">single public key to be added</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="add_pk"> + <callback name="add_pk" throws="1"> + <source-position filename="ostree-sign.h" line="87"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="212">@TRUE in case if the key could be added successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="203">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </parameter> + <parameter name="public_key" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="204">single public key to be added</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + <field name="load_pk"> + <callback name="load_pk" throws="1"> + <source-position filename="ostree-sign.h" line="90"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="247">@TRUE in case if at least one key could be load successfully, +@FALSE in case of error (@error will contain the reason).</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="231">an #OstreeSign object</doc> + <type name="Sign" c:type="OstreeSign*"/> + </parameter> + <parameter name="options" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="232">any options</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </callback> + </field> + </record> + <enumeration name="StaticDeltaGenerateOpt" + c:type="OstreeStaticDeltaGenerateOpt"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1089">Parameters controlling optimization of static deltas.</doc> + <source-position filename="ostree-repo.h" line="1099"/> + <member name="lowlatency" + value="0" + c:identifier="OSTREE_STATIC_DELTA_GENERATE_OPT_LOWLATENCY"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1091">Optimize for speed of delta creation over space</doc> + </member> + <member name="major" + value="1" + c:identifier="OSTREE_STATIC_DELTA_GENERATE_OPT_MAJOR"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1092">Optimize for delta size (may be very slow)</doc> + </member> + </enumeration> + <enumeration name="StaticDeltaIndexFlags" + c:type="OstreeStaticDeltaIndexFlags"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1111">Flags controlling static delta index generation.</doc> + <source-position filename="ostree-repo.h" line="1119"/> + <member name="static_delta_index_flags_none" + value="0" + c:identifier="OSTREE_STATIC_DELTA_INDEX_FLAGS_NONE"> + <doc xml:space="preserve" + filename="ostree-repo.h" + line="1113">No special flags</doc> + </member> + </enumeration> + <class name="Sysroot" + c:symbol-prefix="sysroot" + c:type="OstreeSysroot" + parent="GObject.Object" + glib:type-name="OstreeSysroot" + glib:get-type="ostree_sysroot_get_type"> + <constructor name="new" c:identifier="ostree_sysroot_new"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="206">Create a new #OstreeSysroot object for the sysroot at @path. If @path is %NULL, +the current visible root file system is used, equivalent to +ostree_sysroot_new_default().</doc> + <source-position filename="ostree-sysroot.h" line="45"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="215">An accessor object for an system root located at @path</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </return-value> + <parameters> + <parameter name="path" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="208">Path to a system root directory, or %NULL to use the + current visible root file system</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_default" + c:identifier="ostree_sysroot_new_default"> + <source-position filename="ostree-sysroot.h" line="48"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="226">An accessor for the current visible root / filesystem</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </return-value> + </constructor> + <function name="get_deployment_origin_path" + c:identifier="ostree_sysroot_get_deployment_origin_path"> + <source-position filename="ostree-sysroot.h" line="108"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1348">Path to deployment origin file</doc> + <type name="Gio.File" c:type="GFile*"/> + </return-value> + <parameters> + <parameter name="deployment_path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1346">A deployment path</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + </parameters> + </function> + <method name="cleanup" c:identifier="ostree_sysroot_cleanup" throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-cleanup.c" + line="541">Delete any state that resulted from a partially completed +transaction, such as incomplete deployments.</doc> + <source-position filename="ostree-sysroot.h" line="136"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-cleanup.c" + line="543">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-cleanup.c" + line="544">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="cleanup_prune_repo" + c:identifier="ostree_sysroot_cleanup_prune_repo" + version="2018.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-cleanup.c" + line="465">Prune the system repository. This is a thin wrapper +around ostree_repo_prune_from_reachable(); the primary +addition is that this function automatically gathers +all deployed commits into the reachable set. + +You generally want to at least set the `OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY` +flag in @options. A commit traversal depth of `0` is assumed. + +Locking: exclusive</doc> + <source-position filename="ostree-sysroot.h" line="147"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="sysroot" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-cleanup.c" + line="467">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="options" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-cleanup.c" + line="468">Flags controlling pruning</doc> + <type name="RepoPruneOptions" c:type="OstreeRepoPruneOptions*"/> + </parameter> + <parameter name="out_objects_total" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot-cleanup.c" + line="469">Number of objects found</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="out_objects_pruned" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot-cleanup.c" + line="470">Number of objects deleted</doc> + <type name="gint" c:type="gint*"/> + </parameter> + <parameter name="out_pruned_object_size_total" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot-cleanup.c" + line="471">Storage size in bytes of objects deleted</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-cleanup.c" + line="472">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="deploy_tree" + c:identifier="ostree_sysroot_deploy_tree" + version="2018.5" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2960">Older version of ostree_sysroot_stage_tree_with_options().</doc> + <source-position filename="ostree-sysroot.h" line="214"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2962">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="osname" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2963">osname to use for merge deployment</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="revision" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2964">Checksum to add</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="origin" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2965">Origin to use for upgrades</doc> + <type name="GLib.KeyFile" c:type="GKeyFile*"/> + </parameter> + <parameter name="provided_merge_deployment" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2966">Use this deployment for merge path</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </parameter> + <parameter name="override_kernel_argv" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2967">Use these as kernel arguments; if %NULL, inherit options from provided_merge_deployment</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="out_new_deployment" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2968">The new deployment path</doc> + <type name="Deployment" c:type="OstreeDeployment**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2969">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="deploy_tree_with_options" + c:identifier="ostree_sysroot_deploy_tree_with_options" + version="2020.7" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2913">Check out deployment tree with revision @revision, performing a 3 +way merge with @provided_merge_deployment for configuration. + +When booted into the sysroot, you should use the +ostree_sysroot_stage_tree() API instead.</doc> + <source-position filename="ostree-sysroot.h" line="225"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2915">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="osname" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2916">osname to use for merge deployment</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="revision" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2917">Checksum to add</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="origin" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2918">Origin to use for upgrades</doc> + <type name="GLib.KeyFile" c:type="GKeyFile*"/> + </parameter> + <parameter name="provided_merge_deployment" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2919">Use this deployment for merge path</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </parameter> + <parameter name="opts" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2920">Options</doc> + <type name="SysrootDeployTreeOpts" + c:type="OstreeSysrootDeployTreeOpts*"/> + </parameter> + <parameter name="out_new_deployment" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2921">The new deployment path</doc> + <type name="Deployment" c:type="OstreeDeployment**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2922">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="deployment_set_kargs" + c:identifier="ostree_sysroot_deployment_set_kargs" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3361">Entirely replace the kernel arguments of @deployment with the +values in @new_kargs.</doc> + <source-position filename="ostree-sysroot.h" line="172"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3363">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="deployment" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3364">A deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </parameter> + <parameter name="new_kargs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3365">Replace deployment's kernel arguments</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3366">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="deployment_set_mutable" + c:identifier="ostree_sysroot_deployment_set_mutable" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3410">By default, deployment directories are not mutable. This function +will allow making them temporarily mutable, for example to allow +layering additional non-OSTree content.</doc> + <source-position filename="ostree-sysroot.h" line="259"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3412">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="deployment" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3413">A deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </parameter> + <parameter name="is_mutable" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3414">Whether or not deployment's files can be changed</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3415">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="deployment_set_pinned" + c:identifier="ostree_sysroot_deployment_set_pinned" + version="2018.3" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="2212">By default, deployments may be subject to garbage collection. Typical uses of +libostree only retain at most 2 deployments. If @is_pinned is `TRUE`, a +metadata bit will be set causing libostree to avoid automatic GC of the +deployment. However, this is really an "advisory" note; it's still possible +for e.g. older versions of libostree unaware of pinning to GC the deployment. + +This function does nothing and returns successfully if the deployment +is already in the desired pinning state. It is an error to try to pin +the staged deployment (as it's not in the bootloader entries).</doc> + <source-position filename="ostree-sysroot.h" line="266"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="2214">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="deployment" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="2215">A deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </parameter> + <parameter name="is_pinned" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="2216">Whether or not deployment will be automatically GC'd</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + </parameters> + </method> + <method name="deployment_unlock" + c:identifier="ostree_sysroot_deployment_unlock" + version="2016.4" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="2006">Configure the target deployment @deployment such that it +is writable. There are multiple modes, essentially differing +in whether or not any changes persist across reboot. + +The `OSTREE_DEPLOYMENT_UNLOCKED_HOTFIX` state is persistent +across reboots.</doc> + <source-position filename="ostree-sysroot.h" line="272"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="2008">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="deployment" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="2009">Deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </parameter> + <parameter name="unlocked_state" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="2010">Transition to this unlocked state</doc> + <type name="DeploymentUnlockedState" + c:type="OstreeDeploymentUnlockedState"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="2011">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="ensure_initialized" + c:identifier="ostree_sysroot_ensure_initialized" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="427">Ensure that @self is set up as a valid rootfs, by creating +/ostree/repo, among other things.</doc> + <source-position filename="ostree-sysroot.h" line="81"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="429">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="430">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="get_booted_deployment" + c:identifier="ostree_sysroot_get_booted_deployment"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1237">This function may only be called if the sysroot is loaded.</doc> + <source-position filename="ostree-sysroot.h" line="92"/> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1243">The currently booted deployment, or %NULL if none</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1239">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_bootversion" + c:identifier="ostree_sysroot_get_bootversion"> + <source-position filename="ostree-sysroot.h" line="86"/> + <return-value transfer-ownership="none"> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_deployment_directory" + c:identifier="ostree_sysroot_get_deployment_directory"> + <source-position filename="ostree-sysroot.h" line="100"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1334">Path to deployment root directory</doc> + <type name="Gio.File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1331">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="deployment" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1332">A deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </parameter> + </parameters> + </method> + <method name="get_deployment_dirpath" + c:identifier="ostree_sysroot_get_deployment_dirpath"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1308">Note this function only returns a *relative* path - if you want +to access, it, you must either use fd-relative api such as openat(), +or concatenate it with the full ostree_sysroot_get_path().</doc> + <source-position filename="ostree-sysroot.h" line="104"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1317">Path to deployment root directory, relative to sysroot</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1310">Repo</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="deployment" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1311">A deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </parameter> + </parameters> + </method> + <method name="get_deployments" + c:identifier="ostree_sysroot_get_deployments"> + <source-position filename="ostree-sysroot.h" line="90"/> + <return-value transfer-ownership="container"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1295">Ordered list of deployments</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="Deployment"/> + </array> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1293">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_fd" c:identifier="ostree_sysroot_get_fd"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="363">Access a file descriptor that refers to the root directory of this sysroot. +ostree_sysroot_initialize() (or ostree_sysroot_load()) must have been invoked +prior to calling this function.</doc> + <source-position filename="ostree-sysroot.h" line="60"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="371">A file descriptor valid for the lifetime of @self</doc> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="365">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_merge_deployment" + c:identifier="ostree_sysroot_get_merge_deployment"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1561">Find the deployment to use as a configuration merge source; this is +the first one in the current deployment list which matches osname.</doc> + <source-position filename="ostree-sysroot.h" line="285"/> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1569">Configuration merge deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1563">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="osname" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1564">Operating system group</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="get_path" c:identifier="ostree_sysroot_get_path"> + <source-position filename="ostree-sysroot.h" line="54"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="265">Path to rootfs</doc> + <type name="Gio.File" c:type="GFile*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="263">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_repo" + c:identifier="ostree_sysroot_get_repo" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1359">Retrieve the OSTree repository in sysroot @self. The repo is guaranteed to be open +(see ostree_repo_open()).</doc> + <source-position filename="ostree-sysroot.h" line="166"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1369">%TRUE on success, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1361">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="out_repo" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1362">Repository in sysroot @self</doc> + <type name="Repo" c:type="OstreeRepo**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1363">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="get_staged_deployment" + c:identifier="ostree_sysroot_get_staged_deployment" + version="2018.5"> + <source-position filename="ostree-sysroot.h" line="97"/> + <return-value transfer-ownership="none" nullable="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1279">The currently staged deployment, or %NULL if none</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1277">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_subbootversion" + c:identifier="ostree_sysroot_get_subbootversion"> + <source-position filename="ostree-sysroot.h" line="88"/> + <return-value transfer-ownership="none"> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + </parameters> + </method> + <method name="init_osname" + c:identifier="ostree_sysroot_init_osname" + version="2016.4" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1757">Initialize the directory structure for an "osname", which is a +group of operating system deployments, with a shared `/var`. One +is required for generating a deployment.</doc> + <source-position filename="ostree-sysroot.h" line="130"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1759">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="osname" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1760">Name group of operating system checkouts</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1761">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="initialize" + c:identifier="ostree_sysroot_initialize" + version="2020.1" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="956">Subset of ostree_sysroot_load(); performs basic initialization. Notably, one +can invoke `ostree_sysroot_get_fd()` after calling this function. + +It is not necessary to call this function if ostree_sysroot_load() is +invoked.</doc> + <source-position filename="ostree-sysroot.h" line="63"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="958">sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + </parameters> + </method> + <method name="is_booted" + c:identifier="ostree_sysroot_is_booted" + version="2020.1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="380">Can only be invoked after `ostree_sysroot_initialize()`.</doc> + <source-position filename="ostree-sysroot.h" line="57"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="386">%TRUE iff the sysroot points to a booted deployment</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="382">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + </parameters> + </method> + <method name="load" c:identifier="ostree_sysroot_load" throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="912">Load deployment list, bootversion, and subbootversion from the +rootfs @self.</doc> + <source-position filename="ostree-sysroot.h" line="67"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="914">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="915">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="load_if_changed" + c:identifier="ostree_sysroot_load_if_changed" + version="2016.4" + throws="1"> + <source-position filename="ostree-sysroot.h" line="72"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1171">#OstreeSysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="out_changed" + direction="out" + caller-allocates="1" + transfer-ownership="none"> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1173">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="lock" c:identifier="ostree_sysroot_lock" throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1611">Acquire an exclusive multi-process write lock for @self. This call +blocks until the lock has been acquired. The lock is not +reentrant. + +Release the lock with ostree_sysroot_unlock(). The lock will also +be released if @self is deallocated.</doc> + <source-position filename="ostree-sysroot.h" line="111"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1613">Self</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + </parameters> + </method> + <method name="lock_async" c:identifier="ostree_sysroot_lock_async"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1721">An asynchronous version of ostree_sysroot_lock().</doc> + <source-position filename="ostree-sysroot.h" line="118"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1723">Self</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1724">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" + transfer-ownership="none" + nullable="1" + allow-none="1" + scope="async" + closure="2"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1725">Callback</doc> + <type name="Gio.AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1726">User data</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </method> + <method name="lock_finish" + c:identifier="ostree_sysroot_lock_finish" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1740">Call when ostree_sysroot_lock_async() is ready.</doc> + <source-position filename="ostree-sysroot.h" line="123"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1742">Self</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1743">Result</doc> + <type name="Gio.AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </method> + <method name="origin_new_from_refspec" + c:identifier="ostree_sysroot_origin_new_from_refspec"> + <source-position filename="ostree-sysroot.h" line="290"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1600">A new config file which sets @refspec as an origin</doc> + <type name="GLib.KeyFile" c:type="GKeyFile*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1597">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="refspec" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1598">A refspec</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </method> + <method name="prepare_cleanup" + c:identifier="ostree_sysroot_prepare_cleanup" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-cleanup.c" + line="558">Like ostree_sysroot_cleanup() in that it cleans up incomplete deployments +and old boot versions, but does NOT prune the repository.</doc> + <source-position filename="ostree-sysroot.h" line="141"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-cleanup.c" + line="560">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-cleanup.c" + line="561">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="query_deployments_for" + c:identifier="ostree_sysroot_query_deployments_for" + version="2017.7"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1504">Find the pending and rollback deployments for @osname. Pass %NULL for @osname +to use the booted deployment's osname. By default, pending deployment is the +first deployment in the order that matches @osname, and @rollback will be the +next one after the booted deployment, or the deployment after the pending if +we're not looking at the booted deployment.</doc> + <source-position filename="ostree-sysroot.h" line="279"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1506">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="osname" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1507">"stateroot" name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_pending" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1508">The pending deployment</doc> + <type name="Deployment" c:type="OstreeDeployment**"/> + </parameter> + <parameter name="out_rollback" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1509">The rollback deployment</doc> + <type name="Deployment" c:type="OstreeDeployment**"/> + </parameter> + </parameters> + </method> + <method name="repo" c:identifier="ostree_sysroot_repo" version="2017.7"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1384">This function is a variant of ostree_sysroot_get_repo() that cannot fail, and +returns a cached repository. Can only be called after ostree_sysroot_initialize() +or ostree_sysroot_load() has been invoked successfully.</doc> + <source-position filename="ostree-sysroot.h" line="163"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1392">The OSTree repository in sysroot @self.</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1386">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + </parameters> + </method> + <method name="require_booted_deployment" + c:identifier="ostree_sysroot_require_booted_deployment" + version="2021.1" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1255">Find the booted deployment, or return an error if not booted via OSTree.</doc> + <source-position filename="ostree-sysroot.h" line="95"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1261">The currently booted deployment, or an error</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1257">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + </parameters> + </method> + <method name="set_mount_namespace_in_use" + c:identifier="ostree_sysroot_set_mount_namespace_in_use" + version="2020.1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="234">If this function is invoked, then libostree will assume that +a private Linux mount namespace has been created by the process. +The primary use case for this is to have e.g. /sysroot mounted +read-only by default. + +If this function has been called, then when a function which requires +writable access is invoked, libostree will automatically remount as writable +any mount points on which it operates. This currently is just `/sysroot` and +`/boot`. + +If you invoke this function, it must be before ostree_sysroot_load(); it may +be invoked before or after ostree_sysroot_initialize().</doc> + <source-position filename="ostree-sysroot.h" line="51"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + </parameters> + </method> + <method name="simple_write_deployment" + c:identifier="ostree_sysroot_simple_write_deployment" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1821">Prepend @new_deployment to the list of deployments, commit, and +cleanup. By default, all other deployments for the given @osname +except the merge deployment and the booted deployment will be +garbage collected. + +If %OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN is +specified, then all current deployments will be kept. + +If %OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_PENDING is +specified, then pending deployments will be kept. + +If %OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_ROLLBACK is +specified, then rollback deployments will be kept. + +If %OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NOT_DEFAULT is +specified, then instead of prepending, the new deployment will be +added right after the booted or merge deployment, instead of first. + +If %OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NO_CLEAN is +specified, then no cleanup will be performed after adding the +deployment. Make sure to call ostree_sysroot_cleanup() sometime +later, instead.</doc> + <source-position filename="ostree-sysroot.h" line="303"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="sysroot" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1823">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="osname" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1824">OS name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="new_deployment" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1825">Prepend this deployment to the list</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </parameter> + <parameter name="merge_deployment" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1826">Use this deployment for configuration merge</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1827">Flags controlling behavior</doc> + <type name="SysrootSimpleWriteDeploymentFlags" + c:type="OstreeSysrootSimpleWriteDeploymentFlags"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1828">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="stage_overlay_initrd" + c:identifier="ostree_sysroot_stage_overlay_initrd" + version="2020.7" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3052">Stage an overlay initrd to be used in an upcoming deployment. Returns a checksum which +can be passed to ostree_sysroot_deploy_tree_with_options() or +ostree_sysroot_stage_tree_with_options() via the `overlay_initrds` array option.</doc> + <source-position filename="ostree-sysroot.h" line="199"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3054">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="fd" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3055">File descriptor to overlay initrd</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="out_checksum" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3056">Overlay initrd checksum</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3057">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="stage_tree" + c:identifier="ostree_sysroot_stage_tree" + version="2018.5" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3109">Older version of ostree_sysroot_stage_tree_with_options().</doc> + <source-position filename="ostree-sysroot.h" line="236"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3111">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="osname" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3112">osname to use for merge deployment</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="revision" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3113">Checksum to add</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="origin" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3114">Origin to use for upgrades</doc> + <type name="GLib.KeyFile" c:type="GKeyFile*"/> + </parameter> + <parameter name="merge_deployment" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3115">Use this deployment for merge path</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </parameter> + <parameter name="override_kernel_argv" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3116">Use these as kernel arguments; if %NULL, inherit options from provided_merge_deployment</doc> + <array c:type="char**"> + <type name="utf8"/> + </array> + </parameter> + <parameter name="out_new_deployment" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3117">The new deployment path</doc> + <type name="Deployment" c:type="OstreeDeployment**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3118">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="stage_tree_with_options" + c:identifier="ostree_sysroot_stage_tree_with_options" + version="2020.7" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3143">Like ostree_sysroot_deploy_tree(), but "finalization" only occurs at OS +shutdown time.</doc> + <source-position filename="ostree-sysroot.h" line="247"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3145">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="osname" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3146">osname to use for merge deployment</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="revision" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3147">Checksum to add</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="origin" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3148">Origin to use for upgrades</doc> + <type name="GLib.KeyFile" c:type="GKeyFile*"/> + </parameter> + <parameter name="merge_deployment" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3149">Use this deployment for merge path</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </parameter> + <parameter name="opts" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3150">Options</doc> + <type name="SysrootDeployTreeOpts" + c:type="OstreeSysrootDeployTreeOpts*"/> + </parameter> + <parameter name="out_new_deployment" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3151">The new deployment path</doc> + <type name="Deployment" c:type="OstreeDeployment**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="3152">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="try_lock" + c:identifier="ostree_sysroot_try_lock" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1637">Try to acquire an exclusive multi-process write lock for @self. If +another process holds the lock, this function will return +immediately, setting @out_acquired to %FALSE, and returning %TRUE +(and no error). + +Release the lock with ostree_sysroot_unlock(). The lock will also +be released if @self is deallocated.</doc> + <source-position filename="ostree-sysroot.h" line="114"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1639">Self</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="out_acquired" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1640">Whether or not the lock has been acquired</doc> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + </parameters> + </method> + <method name="unload" c:identifier="ostree_sysroot_unload"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="409">Release any resources such as file descriptors referring to the +root directory of this sysroot. Normally, those resources are +cleared by finalization, but in garbage collected languages that +may not be predictable. + +This undoes the effect of `ostree_sysroot_load()`.</doc> + <source-position filename="ostree-sysroot.h" line="78"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="411">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + </parameters> + </method> + <method name="unlock" c:identifier="ostree_sysroot_unlock"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1685">Clear the lock previously acquired with ostree_sysroot_lock(). It +is safe to call this function if the lock has not been previously +acquired.</doc> + <source-position filename="ostree-sysroot.h" line="127"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="1687">Self</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + </parameters> + </method> + <method name="write_deployments" + c:identifier="ostree_sysroot_write_deployments" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2292">Older version of ostree_sysroot_write_deployments_with_options(). This +version will perform post-deployment cleanup by default.</doc> + <source-position filename="ostree-sysroot.h" line="179"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2294">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="new_deployments" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2295">List of new deployments</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="Deployment"/> + </array> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2296">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_deployments_with_options" + c:identifier="ostree_sysroot_write_deployments_with_options" + version="2017.4" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2422">Assuming @new_deployments have already been deployed in place on disk via +ostree_sysroot_deploy_tree(), atomically update bootloader configuration. By +default, no post-transaction cleanup will be performed. You should invoke +ostree_sysroot_cleanup() at some point after the transaction, or specify +`do_postclean` in @opts. Skipping the post-transaction cleanup is useful +if for example you want to control pruning of the repository.</doc> + <source-position filename="ostree-sysroot.h" line="192"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2424">Sysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="new_deployments" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2425">List of new deployments</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="Deployment"/> + </array> + </parameter> + <parameter name="opts" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2426">Options</doc> + <type name="SysrootWriteDeploymentsOpts" + c:type="OstreeSysrootWriteDeploymentsOpts*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="2427">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="write_origin_file" + c:identifier="ostree_sysroot_write_origin_file" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="950">Immediately replace the origin file of the referenced @deployment +with the contents of @new_origin. If @new_origin is %NULL, +this function will write the current origin of @deployment.</doc> + <source-position filename="ostree-sysroot.h" line="156"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="sysroot" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="952">System root</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </instance-parameter> + <parameter name="deployment" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="953">Deployment</doc> + <type name="Deployment" c:type="OstreeDeployment*"/> + </parameter> + <parameter name="new_origin" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="954">Origin content</doc> + <type name="GLib.KeyFile" c:type="GKeyFile*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-deploy.c" + line="955">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <property name="path" + writable="1" + construct-only="1" + transfer-ownership="none"> + <type name="Gio.File"/> + </property> + <glib:signal name="journal-msg" when="last" version="2017.10"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="162">libostree will log to the journal various events, such as the /etc merge +status, and transaction completion. Connect to this signal to also +synchronously receive the text for those messages. This is intended to be +used by command line tools which link to libostree as a library. + +Currently, the structured data is only available via the systemd journal.</doc> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="msg" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="165">Human-readable string (should not contain newlines)</doc> + <type name="utf8" c:type="gchar*"/> + </parameter> + </parameters> + </glib:signal> + </class> + <record name="SysrootDeployTreeOpts" c:type="OstreeSysrootDeployTreeOpts"> + <source-position filename="ostree-sysroot.h" line="211"/> + <field name="unused_bools" writable="1"> + <array zero-terminated="0" fixed-size="8"> + <type name="gboolean" c:type="gboolean"/> + </array> + </field> + <field name="unused_ints" writable="1"> + <array zero-terminated="0" fixed-size="8"> + <type name="gint" c:type="int"/> + </array> + </field> + <field name="override_kernel_argv" writable="1"> + <type name="utf8" c:type="char**"/> + </field> + <field name="overlay_initrds" writable="1"> + <type name="utf8" c:type="char**"/> + </field> + <field name="unused_ptrs" writable="1"> + <array zero-terminated="0" fixed-size="6"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <bitfield name="SysrootSimpleWriteDeploymentFlags" + c:type="OstreeSysrootSimpleWriteDeploymentFlags"> + <source-position filename="ostree-sysroot.h" line="300"/> + <member name="none" + value="0" + c:identifier="OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NONE"> + </member> + <member name="retain" + value="1" + c:identifier="OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN"> + </member> + <member name="not_default" + value="2" + c:identifier="OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NOT_DEFAULT"> + </member> + <member name="no_clean" + value="4" + c:identifier="OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NO_CLEAN"> + </member> + <member name="retain_pending" + value="8" + c:identifier="OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_PENDING"> + </member> + <member name="retain_rollback" + value="16" + c:identifier="OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_ROLLBACK"> + </member> + </bitfield> + <class name="SysrootUpgrader" + c:symbol-prefix="sysroot_upgrader" + c:type="OstreeSysrootUpgrader" + parent="GObject.Object" + glib:type-name="OstreeSysrootUpgrader" + glib:get-type="ostree_sysroot_upgrader_get_type"> + <implements name="Gio.Initable"/> + <constructor name="new" + c:identifier="ostree_sysroot_upgrader_new" + throws="1"> + <source-position filename="ostree-sysroot-upgrader.h" line="54"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="271">An upgrader</doc> + <type name="SysrootUpgrader" c:type="OstreeSysrootUpgrader*"/> + </return-value> + <parameters> + <parameter name="sysroot" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="267">An #OstreeSysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="268">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_for_os" + c:identifier="ostree_sysroot_upgrader_new_for_os" + throws="1"> + <source-position filename="ostree-sysroot-upgrader.h" line="59"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="289">An upgrader</doc> + <type name="SysrootUpgrader" c:type="OstreeSysrootUpgrader*"/> + </return-value> + <parameters> + <parameter name="sysroot" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="284">An #OstreeSysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </parameter> + <parameter name="osname" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="285">Operating system name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="286">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </constructor> + <constructor name="new_for_os_with_flags" + c:identifier="ostree_sysroot_upgrader_new_for_os_with_flags" + throws="1"> + <source-position filename="ostree-sysroot-upgrader.h" line="65"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="309">An upgrader</doc> + <type name="SysrootUpgrader" c:type="OstreeSysrootUpgrader*"/> + </return-value> + <parameters> + <parameter name="sysroot" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="303">An #OstreeSysroot</doc> + <type name="Sysroot" c:type="OstreeSysroot*"/> + </parameter> + <parameter name="osname" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="304">Operating system name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="305">Flags</doc> + <type name="SysrootUpgraderFlags" + c:type="OstreeSysrootUpgraderFlags"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="306">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </constructor> + <function name="check_timestamps" + c:identifier="ostree_sysroot_upgrader_check_timestamps" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="401">Check that the timestamp on @to_rev is equal to or newer than +@from_rev. This protects systems against man-in-the-middle +attackers which provide a client with an older commit.</doc> + <source-position filename="ostree-sysroot-upgrader.h" line="83"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="403">Repo</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="from_rev" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="404">From revision</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="to_rev" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="405">To revision</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <method name="deploy" + c:identifier="ostree_sysroot_upgrader_deploy" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="630">Write the new deployment to disk, perform a configuration merge +with /etc, and update the bootloader configuration.</doc> + <source-position filename="ostree-sysroot-upgrader.h" line="114"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="632">Self</doc> + <type name="SysrootUpgrader" c:type="OstreeSysrootUpgrader*"/> + </instance-parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="633">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="dup_origin" + c:identifier="ostree_sysroot_upgrader_dup_origin"> + <source-position filename="ostree-sysroot-upgrader.h" line="74"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="338">A copy of the origin file, or %NULL if unknown</doc> + <type name="GLib.KeyFile" c:type="GKeyFile*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="336">Sysroot</doc> + <type name="SysrootUpgrader" c:type="OstreeSysrootUpgrader*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_origin" + c:identifier="ostree_sysroot_upgrader_get_origin"> + <source-position filename="ostree-sysroot-upgrader.h" line="72"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="326">The origin file, or %NULL if unknown</doc> + <type name="GLib.KeyFile" c:type="GKeyFile*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="324">Sysroot</doc> + <type name="SysrootUpgrader" c:type="OstreeSysrootUpgrader*"/> + </instance-parameter> + </parameters> + </method> + <method name="get_origin_description" + c:identifier="ostree_sysroot_upgrader_get_origin_description"> + <source-position filename="ostree-sysroot-upgrader.h" line="80"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="391">A one-line descriptive summary of the origin, or %NULL if unknown</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="389">Upgrader</doc> + <type name="SysrootUpgrader" c:type="OstreeSysrootUpgrader*"/> + </instance-parameter> + </parameters> + </method> + <method name="pull" + c:identifier="ostree_sysroot_upgrader_pull" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="440">Perform a pull from the origin. First check if the ref has +changed, if so download the linked objects, and store the updated +ref locally. Then @out_changed will be %TRUE. + +If the origin remote is unchanged, @out_changed will be set to +%FALSE.</doc> + <source-position filename="ostree-sysroot-upgrader.h" line="95"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="442">Upgrader</doc> + <type name="SysrootUpgrader" c:type="OstreeSysrootUpgrader*"/> + </instance-parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="443">Flags controlling pull behavior</doc> + <type name="RepoPullFlags" c:type="OstreeRepoPullFlags"/> + </parameter> + <parameter name="upgrader_flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="444">Flags controlling upgrader behavior</doc> + <type name="SysrootUpgraderPullFlags" + c:type="OstreeSysrootUpgraderPullFlags"/> + </parameter> + <parameter name="progress" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="445">Progress</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </parameter> + <parameter name="out_changed" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="446">Whether or not the origin changed</doc> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="447">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="pull_one_dir" + c:identifier="ostree_sysroot_upgrader_pull_one_dir" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="469">Like ostree_sysroot_upgrader_pull(), but allows retrieving just a +subpath of the tree. This can be used to download metadata files +from inside the tree such as package databases.</doc> + <source-position filename="ostree-sysroot-upgrader.h" line="104"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="471">Upgrader</doc> + <type name="SysrootUpgrader" c:type="OstreeSysrootUpgrader*"/> + </instance-parameter> + <parameter name="dir_to_pull" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="472">Subdirectory path (should include a leading /)</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="473">Flags controlling pull behavior</doc> + <type name="RepoPullFlags" c:type="OstreeRepoPullFlags"/> + </parameter> + <parameter name="upgrader_flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="474">Flags controlling upgrader behavior</doc> + <type name="SysrootUpgraderPullFlags" + c:type="OstreeSysrootUpgraderPullFlags"/> + </parameter> + <parameter name="progress" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="475">Progress</doc> + <type name="AsyncProgress" c:type="OstreeAsyncProgress*"/> + </parameter> + <parameter name="out_changed" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="476">Whether or not the origin changed</doc> + <type name="gboolean" c:type="gboolean*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="477">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <method name="set_origin" + c:identifier="ostree_sysroot_upgrader_set_origin" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="361">Replace the origin with @origin.</doc> + <source-position filename="ostree-sysroot-upgrader.h" line="76"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <instance-parameter name="self" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="363">Sysroot</doc> + <type name="SysrootUpgrader" c:type="OstreeSysrootUpgrader*"/> + </instance-parameter> + <parameter name="origin" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="364">The new origin</doc> + <type name="GLib.KeyFile" c:type="GKeyFile*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="365">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </method> + <property name="flags" + writable="1" + construct-only="1" + transfer-ownership="none"> + <type name="SysrootUpgraderFlags"/> + </property> + <property name="osname" + writable="1" + construct-only="1" + transfer-ownership="none"> + <type name="utf8" c:type="gchar*"/> + </property> + <property name="sysroot" + writable="1" + construct-only="1" + transfer-ownership="none"> + <type name="Sysroot"/> + </property> + </class> + <bitfield name="SysrootUpgraderFlags" + glib:type-name="OstreeSysrootUpgraderFlags" + glib:get-type="ostree_sysroot_upgrader_flags_get_type" + c:type="OstreeSysrootUpgraderFlags"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.h" + line="32">Flags controlling operation of an #OstreeSysrootUpgrader.</doc> + <member name="ignore_unconfigured" + value="2" + c:identifier="OSTREE_SYSROOT_UPGRADER_FLAGS_IGNORE_UNCONFIGURED" + glib:nick="ignore-unconfigured"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.h" + line="35">Do not error if the origin has an unconfigured-state key</doc> + </member> + <member name="stage" + value="4" + c:identifier="OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE" + glib:nick="stage"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.h" + line="36">Enable "staging" (finalization at shutdown); recommended + (Since: 2021.4)</doc> + </member> + </bitfield> + <bitfield name="SysrootUpgraderPullFlags" + c:type="OstreeSysrootUpgraderPullFlags"> + <source-position filename="ostree-sysroot-upgrader.h" line="92"/> + <member name="none" + value="0" + c:identifier="OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_NONE"> + </member> + <member name="allow_older" + value="1" + c:identifier="OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_ALLOW_OLDER"> + </member> + <member name="synthetic" + value="2" + c:identifier="OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_SYNTHETIC"> + </member> + </bitfield> + <record name="SysrootWriteDeploymentsOpts" + c:type="OstreeSysrootWriteDeploymentsOpts"> + <source-position filename="ostree-sysroot.h" line="189"/> + <field name="do_postclean" writable="1"> + <type name="gboolean" c:type="gboolean"/> + </field> + <field name="unused_bools" writable="1"> + <array zero-terminated="0" fixed-size="7"> + <type name="gboolean" c:type="gboolean"/> + </array> + </field> + <field name="unused_ints" writable="1"> + <array zero-terminated="0" fixed-size="7"> + <type name="gint" c:type="int"/> + </array> + </field> + <field name="unused_ptrs" writable="1"> + <array zero-terminated="0" fixed-size="7"> + <type name="gpointer" c:type="gpointer"/> + </array> + </field> + </record> + <constant name="TIMESTAMP" value="0" c:type="OSTREE_TIMESTAMP"> + <doc xml:space="preserve" + filename="ostree-core.h" + line="180">The mtime used for stored files. This was originally 0, changed to 1 for +a few releases, then was reverted due to regressions it introduced from +users who had been using zero before.</doc> + <source-position filename="ostree-core.h" line="187"/> + <type name="gint" c:type="gint"/> + </constant> + <constant name="TREE_GVARIANT_STRING" + value="(a(say)a(sayay))" + c:type="OSTREE_TREE_GVARIANT_STRING"> + <source-position filename="ostree-core.h" line="136"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="VERSION" + value="2022.200000" + c:type="OSTREE_VERSION" + version="2017.4"> + <doc xml:space="preserve" + filename="ostree-version.h" + line="46">ostree version.</doc> + <source-position filename="ostree-version.h" line="53"/> + <type name="gdouble" c:type="gdouble"/> + </constant> + <constant name="VERSION_S" + value="2022.2" + c:type="OSTREE_VERSION_S" + version="2017.4"> + <doc xml:space="preserve" + filename="ostree-version.h" + line="55">ostree version, encoded as a string, useful for printing and +concatenation.</doc> + <source-position filename="ostree-version.h" line="63"/> + <type name="utf8" c:type="gchar*"/> + </constant> + <constant name="YEAR_VERSION" + value="2022" + c:type="OSTREE_YEAR_VERSION" + version="2017.4"> + <doc xml:space="preserve" + filename="ostree-version.h" + line="28">ostree year version component (e.g. 2017 if %OSTREE_VERSION is 2017.2)</doc> + <source-position filename="ostree-version.h" line="35"/> + <type name="gint" c:type="gint"/> + </constant> + <docsection name="bloom"> + <doc xml:space="preserve" + filename="ostree-bloom.c" + line="34">#OstreeBloom is an implementation of a bloom filter which supports writing to +and loading from a #GBytes bit array. The caller must store metadata about +the bloom filter (its hash function and `k` parameter value) separately, as +the same values must be used when reading from a serialised bit array as were +used to build the array in the first place. + +This is a standard implementation of a bloom filter, and background reading +on the theory can be +[found on Wikipedia](https://en.wikipedia.org/wiki/Bloom_filter). In +particular, a bloom filter is parameterised by `m` and `k` parameters: the +size of the bit array (in bits) is `m`, and the number of hash functions +applied to each element is `k`. Bloom filters require a universal hash +function which can be parameterised by `k`. We have #OstreeBloomHashFunc, +with ostree_str_bloom_hash() being an implementation for strings. + +The serialised output from a bloom filter is guaranteed to be stable across +versions of libostree as long as the same values for `k` and the hash +function are used. + +#OstreeBloom is mutable when constructed with ostree_bloom_new(), and elements +can be added to it using ostree_bloom_add_element(), until ostree_bloom_seal() +is called to serialise it and make it immutable. After then, the bloom filter +can only be queried using ostree_bloom_maybe_contains(). + +If constructed with ostree_bloom_new_from_bytes(), the bloom filter is +immutable from construction, and can only be queried. + +Reference: + - https://en.wikipedia.org/wiki/Bloom_filter + - https://llimllib.github.io/bloomfilter-tutorial/</doc> + </docsection> + <function name="break_hardlink" + c:identifier="ostree_break_hardlink" + version="2017.15" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="781">In many cases using libostree, a program may need to "break" +hardlinks by performing a copy. For example, in order to +logically append to a file. + +This function performs full copying, including e.g. extended +attributes and permissions of both regular files and symbolic links. + +If the file is not hardlinked, this function does nothing and +returns successfully. + +This function does not perform synchronization via `fsync()` or +`fdatasync()`; the idea is this will commonly be done as part +of an `ostree_repo_commit_transaction()`, which itself takes +care of synchronization.</doc> + <source-position filename="ostree-core.h" line="461"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="dfd" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="783">Directory fd</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="784">Path relative to @dfd</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="skip_xattrs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="785">Do not copy extended attributes</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="check_version" + c:identifier="ostree_check_version" + version="2017.4"> + <source-position filename="ostree-core.h" line="590"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2741">%TRUE if current libostree has at least the requested version, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="required_year" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2738">Major/year required</doc> + <type name="guint" c:type="guint"/> + </parameter> + <parameter name="required_release" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2739">Release version required</doc> + <type name="guint" c:type="guint"/> + </parameter> + </parameters> + </function> + <function name="checksum_b64_from_bytes" + c:identifier="ostree_checksum_b64_from_bytes" + version="2016.8"> + <source-position filename="ostree-core.h" line="319"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1567">Modified base64 encoding of @csum + +The "modified" term refers to the fact that instead of '/', the '_' +character is used.</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="csum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1565">An binary checksum of length 32</doc> + <array zero-terminated="0" c:type="const guchar*" fixed-size="32"> + <type name="guint8" c:type="guchar"/> + </array> + </parameter> + </parameters> + </function> + <function name="checksum_b64_inplace_from_bytes" + c:identifier="ostree_checksum_b64_inplace_from_bytes" + introspectable="0"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1495">Overwrite the contents of @buf with modified base64 encoding of @csum. +The "modified" term refers to the fact that instead of '/', the '_' +character is used.</doc> + <source-position filename="ostree-core.h" line="325"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="csum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1497">An binary checksum of length 32</doc> + <array zero-terminated="0" c:type="const guchar*" fixed-size="32"> + <type name="guint8" c:type="guchar"/> + </array> + </parameter> + <parameter name="buf" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1498">Output location, must be at least 44 bytes in length</doc> + <type name="utf8" c:type="char*"/> + </parameter> + </parameters> + </function> + <function name="checksum_b64_inplace_to_bytes" + c:identifier="ostree_checksum_b64_inplace_to_bytes" + introspectable="0"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1376">Overwrite the contents of @buf with stringified version of @csum.</doc> + <source-position filename="ostree-core.h" line="311"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1378">An binary checksum of length 32</doc> + <array zero-terminated="0" c:type="const char*" fixed-size="32"> + <type name="utf8" c:type="char"/> + </array> + </parameter> + <parameter name="buf" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1379">Output location, must be at least 45 bytes in length</doc> + <type name="guint8" c:type="guint8*"/> + </parameter> + </parameters> + </function> + <function name="checksum_b64_to_bytes" + c:identifier="ostree_checksum_b64_to_bytes" + version="2016.8"> + <source-position filename="ostree-core.h" line="309"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1469">Binary version of @checksum.</doc> + <array zero-terminated="0" c:type="guchar*" fixed-size="32"> + <type name="guint8" c:type="guchar"/> + </array> + </return-value> + <parameters> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1467">An ASCII checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="checksum_bytes_peek" + c:identifier="ostree_checksum_bytes_peek"> + <source-position filename="ostree-core.h" line="333"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1586">Binary checksum data in @bytes; do not free. If @bytes does not have the correct length, return %NULL.</doc> + <array zero-terminated="0" c:type="const guchar*" fixed-size="32"> + <type name="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="bytes" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1584">#GVariant of type ay</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <function name="checksum_bytes_peek_validate" + c:identifier="ostree_checksum_bytes_peek_validate" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1599">Like ostree_checksum_bytes_peek(), but also throws @error.</doc> + <source-position filename="ostree-core.h" line="336"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1606">Binary checksum data</doc> + <array zero-terminated="0" c:type="const guchar*" fixed-size="32"> + <type name="guint8"/> + </array> + </return-value> + <parameters> + <parameter name="bytes" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1601">#GVariant of type ay</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <function name="checksum_file" + c:identifier="ostree_checksum_file" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="892">Compute the OSTree checksum for a given file.</doc> + <source-position filename="ostree-core.h" line="454"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="f" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="894">File path</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="895">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="out_csum" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="896">Return location for binary checksum</doc> + <array zero-terminated="0" c:type="guchar**" fixed-size="32"> + <type name="guint8" c:type="guchar*"/> + </array> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="897">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="checksum_file_async" + c:identifier="ostree_checksum_file_async"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1059">Asynchronously compute the OSTree checksum for a given file; +complete with ostree_checksum_file_async_finish().</doc> + <source-position filename="ostree-core.h" line="497"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="f" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1061">File path</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1062">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="io_priority" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1063">Priority for operation, see %G_IO_PRIORITY_DEFAULT</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1064">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" + transfer-ownership="none" + nullable="1" + allow-none="1" + scope="async" + closure="5"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1065">Invoked when operation is complete</doc> + <type name="Gio.AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1066">Data for @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="checksum_file_async_finish" + c:identifier="ostree_checksum_file_async_finish" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1093">Finish computing the OSTree checksum for a given file; see +ostree_checksum_file_async().</doc> + <source-position filename="ostree-core.h" line="505"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="f" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1095">File path</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1096">Async result</doc> + <type name="Gio.AsyncResult" c:type="GAsyncResult*"/> + </parameter> + <parameter name="out_csum" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1097">Return location for binary checksum</doc> + <array zero-terminated="0" c:type="guchar**" fixed-size="32"> + <type name="guint8" c:type="guchar*"/> + </array> + </parameter> + </parameters> + </function> + <function name="checksum_file_at" + c:identifier="ostree_checksum_file_at" + version="2017.13" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="944">Compute the OSTree checksum for a given file. This is an fd-relative version +of ostree_checksum_file() which also takes flags and fills in a caller +allocated buffer.</doc> + <source-position filename="ostree-core.h" line="487"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="dfd" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="946">Directory file descriptor</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="947">Subpath +@stbuf (allow-none): Optional stat buffer</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="stbuf" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <type name="gpointer" c:type="stat*"/> + </parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="949">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="950">Flags +@out_checksum (out) (transfer full): Return location for hex checksum</doc> + <type name="ChecksumFlags" c:type="OstreeChecksumFlags"/> + </parameter> + <parameter name="out_checksum" transfer-ownership="none"> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="952">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="checksum_file_from_input" + c:identifier="ostree_checksum_file_from_input" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="838">Compute the OSTree checksum for a given input.</doc> + <source-position filename="ostree-core.h" line="445"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="file_info" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="840">File information</doc> + <type name="Gio.FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="xattrs" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="841">Optional extended attributes</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="in" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="842">File content, should be %NULL for symbolic links</doc> + <type name="Gio.InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="843">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + <parameter name="out_csum" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="844">Return location for binary checksum</doc> + <array zero-terminated="0" c:type="guchar**" fixed-size="32"> + <type name="guint8" c:type="guchar*"/> + </array> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="845">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="checksum_from_bytes" + c:identifier="ostree_checksum_from_bytes"> + <source-position filename="ostree-core.h" line="315"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1541">String form of @csum</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="csum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1539">An binary checksum of length 32</doc> + <array zero-terminated="0" c:type="const guchar*" fixed-size="32"> + <type name="guint8" c:type="guchar"/> + </array> + </parameter> + </parameters> + </function> + <function name="checksum_from_bytes_v" + c:identifier="ostree_checksum_from_bytes_v"> + <source-position filename="ostree-core.h" line="317"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1555">String form of @csum_bytes</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="csum_v" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1553">#GVariant of type ay</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <function name="checksum_inplace_from_bytes" + c:identifier="ostree_checksum_inplace_from_bytes" + introspectable="0"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1481">Overwrite the contents of @buf with stringified version of @csum.</doc> + <source-position filename="ostree-core.h" line="322"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="csum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1483">An binary checksum of length 32</doc> + <array zero-terminated="0" c:type="const guchar*" fixed-size="32"> + <type name="guint8" c:type="guchar"/> + </array> + </parameter> + <parameter name="buf" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1484">Output location, must be at least OSTREE_SHA256_STRING_LEN+1 bytes in length</doc> + <type name="utf8" c:type="char*"/> + </parameter> + </parameters> + </function> + <function name="checksum_inplace_to_bytes" + c:identifier="ostree_checksum_inplace_to_bytes"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1405">Convert @checksum from a string to binary in-place, without +allocating memory. Use this function in hot code paths.</doc> + <source-position filename="ostree-core.h" line="329"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1407">a SHA256 string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="buf" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1408">Output buffer with at least 32 bytes of space</doc> + <type name="guint8" c:type="guchar*"/> + </parameter> + </parameters> + </function> + <function name="checksum_to_bytes" c:identifier="ostree_checksum_to_bytes"> + <source-position filename="ostree-core.h" line="305"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1441">Binary checksum from @checksum of length 32; free with g_free().</doc> + <array zero-terminated="0" c:type="guchar*" fixed-size="32"> + <type name="guint8" c:type="guchar"/> + </array> + </return-value> + <parameters> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1439">An ASCII checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="checksum_to_bytes_v" + c:identifier="ostree_checksum_to_bytes_v"> + <source-position filename="ostree-core.h" line="307"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1455">New #GVariant of type ay with length 32</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1453">An ASCII checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="cmd__private__" c:identifier="ostree_cmd__private__"> + <source-position filename="ostree-cmdprivate.h" line="40"/> + <return-value transfer-ownership="none"> + <type name="CmdPrivateVTable" c:type="const OstreeCmdPrivateVTable*"/> + </return-value> + </function> + <function name="cmp_checksum_bytes" + c:identifier="ostree_cmp_checksum_bytes"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1327">Compare two binary checksums, using memcmp().</doc> + <source-position filename="ostree-core.h" line="339"/> + <return-value transfer-ownership="none"> + <type name="gint" c:type="int"/> + </return-value> + <parameters> + <parameter name="a" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1329">A binary checksum</doc> + <type name="guint8" c:type="const guchar*"/> + </parameter> + <parameter name="b" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1330">A binary checksum</doc> + <type name="guint8" c:type="const guchar*"/> + </parameter> + </parameters> + </function> + <function name="collection_ref_dupv" + c:identifier="ostree_collection_ref_dupv" + moved-to="CollectionRef.dupv" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="145">Copy an array of #OstreeCollectionRefs, including deep copies of all its +elements. @refs must be %NULL-terminated; it may be empty, but must not be +%NULL.</doc> + <source-position filename="ostree-ref.h" line="69"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="153">a newly allocated copy of @refs</doc> + <array c:type="OstreeCollectionRef**"> + <type name="CollectionRef" c:type="OstreeCollectionRef*"/> + </array> + </return-value> + <parameters> + <parameter name="refs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="147">%NULL-terminated array of #OstreeCollectionRefs</doc> + <array c:type="const OstreeCollectionRef* const*"> + <type name="CollectionRef" c:type="OstreeCollectionRef*"/> + </array> + </parameter> + </parameters> + </function> + <function name="collection_ref_equal" + c:identifier="ostree_collection_ref_equal" + moved-to="CollectionRef.equal" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="124">Compare @ref1 and @ref2 and return %TRUE if they have the same collection ID and +ref name, and %FALSE otherwise. Both @ref1 and @ref2 must be non-%NULL.</doc> + <source-position filename="ostree-ref.h" line="65"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="132">%TRUE if @ref1 and @ref2 are equal, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="ref1" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="126">an #OstreeCollectionRef</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + <parameter name="ref2" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="127">another #OstreeCollectionRef</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="collection_ref_freev" + c:identifier="ostree_collection_ref_freev" + moved-to="CollectionRef.freev" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="173">Free the given array of @refs, including freeing all its elements. @refs +must be %NULL-terminated; it may be empty, but must not be %NULL.</doc> + <source-position filename="ostree-ref.h" line="71"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="refs" transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="175">an array of #OstreeCollectionRefs</doc> + <array c:type="OstreeCollectionRef**"> + <type name="CollectionRef" c:type="OstreeCollectionRef*"/> + </array> + </parameter> + </parameters> + </function> + <function name="collection_ref_hash" + c:identifier="ostree_collection_ref_hash" + moved-to="CollectionRef.hash" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="103">Hash the given @ref. This function is suitable for use with #GHashTable. +@ref must be non-%NULL.</doc> + <source-position filename="ostree-ref.h" line="63"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="110">hash value for @ref</doc> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="ref" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-ref.c" + line="105">an #OstreeCollectionRef</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="commit_get_content_checksum" + c:identifier="ostree_commit_get_content_checksum" + version="2018.2"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2422">There are use cases where one wants a checksum just of the content of a +commit. OSTree commits by default capture the current timestamp, and may have +additional metadata, which means that re-committing identical content +often results in a new checksum. + +By comparing checksums of content, it's possible to easily distinguish +cases where nothing actually changed. + +The content checksums is simply defined as `SHA256(root dirtree_checksum || root_dirmeta_checksum)`, +i.e. the SHA-256 of the root "dirtree" object's checksum concatenated with the +root "dirmeta" checksum (both in binary form, not hexadecimal).</doc> + <source-position filename="ostree-core.h" line="550"/> + <return-value transfer-ownership="full" nullable="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2438">A SHA-256 hex string, or %NULL if @commit_variant is not well-formed</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="commit_variant" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2424">A commit object</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <function name="commit_get_object_sizes" + c:identifier="ostree_commit_get_object_sizes" + version="2020.1" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2596">Reads a commit's "ostree.sizes" metadata and returns an array of +#OstreeCommitSizesEntry in @out_sizes_entries. Each element +represents an object in the commit. If the commit does not contain +the "ostree.sizes" metadata, a %G_IO_ERROR_NOT_FOUND error will be +returned.</doc> + <source-position filename="ostree-core.h" line="585"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="commit_variant" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2598">variant of type %OSTREE_OBJECT_TYPE_COMMIT</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="out_sizes_entries" + direction="out" + caller-allocates="0" + transfer-ownership="container" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2599"> + return location for an array of object size entries</doc> + <array name="GLib.PtrArray" c:type="GPtrArray**"> + <type name="CommitSizesEntry"/> + </array> + </parameter> + </parameters> + </function> + <function name="commit_get_parent" c:identifier="ostree_commit_get_parent"> + <source-position filename="ostree-core.h" line="545"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2393">Checksum of the parent commit of @commit_variant, or %NULL +if none</doc> + <type name="utf8" c:type="gchar*"/> + </return-value> + <parameters> + <parameter name="commit_variant" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2391">Variant of type %OSTREE_OBJECT_TYPE_COMMIT</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <function name="commit_get_timestamp" + c:identifier="ostree_commit_get_timestamp" + version="2016.3"> + <source-position filename="ostree-core.h" line="547"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2410">timestamp in seconds since the Unix epoch, UTC</doc> + <type name="guint64" c:type="guint64"/> + </return-value> + <parameters> + <parameter name="commit_variant" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2408">Commit object</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <function name="commit_metadata_for_bootable" + c:identifier="ostree_commit_metadata_for_bootable" + version="2021.1" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-os.c" + line="31">Update provided @dict with standard metadata for bootable OSTree commits.</doc> + <source-position filename="ostree-repo-os.h" line="43"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="root" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-os.c" + line="33">Root filesystem to be committed</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="dict" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-os.c" + line="34">Dictionary to update</doc> + <type name="GLib.VariantDict" c:type="GVariantDict*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="content_file_parse" + c:identifier="ostree_content_file_parse" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="706">A thin wrapper for ostree_content_stream_parse(); this function +converts an object content stream back into components.</doc> + <source-position filename="ostree-core.h" line="396"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="compressed" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="708">Whether or not the stream is zlib-compressed</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="content_path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="709">Path to file containing content</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="trusted" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="710">If %TRUE, assume the content has been validated</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="out_input" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="711">The raw file content stream</doc> + <type name="Gio.InputStream" c:type="GInputStream**"/> + </parameter> + <parameter name="out_file_info" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="712">Normal metadata</doc> + <type name="Gio.FileInfo" c:type="GFileInfo**"/> + </parameter> + <parameter name="out_xattrs" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="713">Extended attributes</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="714">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="content_file_parse_at" + c:identifier="ostree_content_file_parse_at" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="655">A thin wrapper for ostree_content_stream_parse(); this function +converts an object content stream back into components.</doc> + <source-position filename="ostree-core.h" line="406"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="compressed" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="657">Whether or not the stream is zlib-compressed</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="parent_dfd" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="658">Directory file descriptor</doc> + <type name="gint" c:type="int"/> + </parameter> + <parameter name="path" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="659">Subpath</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="trusted" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="660">If %TRUE, assume the content has been validated</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="out_input" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="661">The raw file content stream</doc> + <type name="Gio.InputStream" c:type="GInputStream**"/> + </parameter> + <parameter name="out_file_info" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="662">Normal metadata</doc> + <type name="Gio.FileInfo" c:type="GFileInfo**"/> + </parameter> + <parameter name="out_xattrs" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="663">Extended attributes</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="664">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="content_stream_parse" + c:identifier="ostree_content_stream_parse" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="556">The reverse of ostree_raw_file_to_content_stream(); this function +converts an object content stream back into components.</doc> + <source-position filename="ostree-core.h" line="385"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="compressed" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="558">Whether or not the stream is zlib-compressed</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="input" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="559">Object content stream</doc> + <type name="Gio.InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="input_length" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="560">Length of stream</doc> + <type name="guint64" c:type="guint64"/> + </parameter> + <parameter name="trusted" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="561">If %TRUE, assume the content has been validated</doc> + <type name="gboolean" c:type="gboolean"/> + </parameter> + <parameter name="out_input" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="562">The raw file content stream</doc> + <type name="Gio.InputStream" c:type="GInputStream**"/> + </parameter> + <parameter name="out_file_info" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="563">Normal metadata</doc> + <type name="Gio.FileInfo" c:type="GFileInfo**"/> + </parameter> + <parameter name="out_xattrs" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="564">Extended attributes</doc> + <type name="GLib.Variant" c:type="GVariant**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="565">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="create_directory_metadata" + c:identifier="ostree_create_directory_metadata"> + <source-position filename="ostree-core.h" line="511"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1145">A new #GVariant containing %OSTREE_OBJECT_TYPE_DIR_META</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="dir_info" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1142">a #GFileInfo containing directory information</doc> + <type name="Gio.FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="xattrs" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1143">Optional extended attributes</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <function name="diff_dirs" c:identifier="ostree_diff_dirs" throws="1"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="197">Compute the difference between directory @a and @b as 3 separate +sets of #OstreeDiffItem in @modified, @removed, and @added.</doc> + <source-position filename="ostree-diff.h" line="64"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="199">Flags</doc> + <type name="DiffFlags" c:type="OstreeDiffFlags"/> + </parameter> + <parameter name="a" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="200">First directory path, or %NULL</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="b" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="201">First directory path</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="modified" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="202">Modified files</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="DiffItem"/> + </array> + </parameter> + <parameter name="removed" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="203">Removed files</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="Gio.File"/> + </array> + </parameter> + <parameter name="added" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="204">Added files</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="Gio.File"/> + </array> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="205">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="diff_dirs_with_options" + c:identifier="ostree_diff_dirs_with_options" + version="2017.4" + throws="1"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="226">Compute the difference between directory @a and @b as 3 separate +sets of #OstreeDiffItem in @modified, @removed, and @added.</doc> + <source-position filename="ostree-diff.h" line="100"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="flags" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="228">Flags</doc> + <type name="DiffFlags" c:type="OstreeDiffFlags"/> + </parameter> + <parameter name="a" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="229">First directory path, or %NULL</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="b" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="230">First directory path</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="modified" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="231">Modified files</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="DiffItem"/> + </array> + </parameter> + <parameter name="removed" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="232">Removed files</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="Gio.File"/> + </array> + </parameter> + <parameter name="added" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="233">Added files</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="Gio.File"/> + </array> + </parameter> + <parameter name="options" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="235">Options</doc> + <type name="DiffDirsOptions" c:type="OstreeDiffDirsOptions*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="234">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="diff_print" c:identifier="ostree_diff_print"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="478">Print the contents of a diff to stdout.</doc> + <source-position filename="ostree-diff.h" line="111"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="a" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="480">First directory path</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="b" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="481">First directory path</doc> + <type name="Gio.File" c:type="GFile*"/> + </parameter> + <parameter name="modified" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="482">Modified files</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="DiffItem"/> + </array> + </parameter> + <parameter name="removed" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="483">Removed files</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="Gio.File"/> + </array> + </parameter> + <parameter name="added" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-diff.c" + line="484">Added files</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="Gio.File"/> + </array> + </parameter> + </parameters> + </function> + <function name="gpg_error_quark" + c:identifier="ostree_gpg_error_quark" + version="2017.10"> + <return-value transfer-ownership="none"> + <type name="GLib.Quark" c:type="GQuark"/> + </return-value> + </function> + <function name="hash_object_name" c:identifier="ostree_hash_object_name"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1308">Use this function with #GHashTable and ostree_object_name_serialize().</doc> + <source-position filename="ostree-core.h" line="363"/> + <return-value transfer-ownership="none"> + <type name="guint" c:type="guint"/> + </return-value> + <parameters> + <parameter name="a" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1310">A #GVariant containing a serialized object</doc> + <type name="gpointer" c:type="gconstpointer"/> + </parameter> + </parameters> + </function> + <function name="kernel_args_cleanup" + c:identifier="ostree_kernel_args_cleanup" + moved-to="KernelArgs.cleanup" + version="2019.3"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="214">Frees the OstreeKernelArgs structure pointed by *loc</doc> + <source-position filename="ostree-kernel-args.h" line="69"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="loc" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="216">Address of an OstreeKernelArgs pointer</doc> + <type name="gpointer" c:type="void*"/> + </parameter> + </parameters> + </function> + <function name="kernel_args_from_string" + c:identifier="ostree_kernel_args_from_string" + moved-to="KernelArgs.from_string" + version="2019.3" + introspectable="0"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="681">Initializes a new OstreeKernelArgs then parses and appends @options +to the empty OstreeKernelArgs</doc> + <source-position filename="ostree-kernel-args.h" line="125"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="688">newly allocated #OstreeKernelArgs with @options appended</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </return-value> + <parameters> + <parameter name="options" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="683">a string representing command line arguments</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="kernel_args_new" + c:identifier="ostree_kernel_args_new" + moved-to="KernelArgs.new" + version="2019.3" + introspectable="0"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="174">Initializes a new OstreeKernelArgs structure and returns it</doc> + <source-position filename="ostree-kernel-args.h" line="66"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-kernel-args.c" + line="179">A newly created #OstreeKernelArgs for kernel arguments</doc> + <type name="KernelArgs" c:type="OstreeKernelArgs*"/> + </return-value> + </function> + <function name="metadata_variant_type" + c:identifier="ostree_metadata_variant_type"> + <source-position filename="ostree-core.h" line="298"/> + <return-value transfer-ownership="none"> + <type name="GLib.VariantType" c:type="const GVariantType*"/> + </return-value> + <parameters> + <parameter name="objtype" transfer-ownership="none"> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + </parameters> + </function> + <function name="object_from_string" + c:identifier="ostree_object_from_string"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1287">Reverse ostree_object_to_string().</doc> + <source-position filename="ostree-core.h" line="379"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1289">An ASCII checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_checksum" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1290">Parsed checksum</doc> + <type name="utf8" c:type="gchar**"/> + </parameter> + <parameter name="out_objtype" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1291">Parsed object type</doc> + <type name="ObjectType" c:type="OstreeObjectType*"/> + </parameter> + </parameters> + </function> + <function name="object_name_deserialize" + c:identifier="ostree_object_name_deserialize"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1357">Reverse ostree_object_name_serialize(). Note that @out_checksum is +only valid for the lifetime of @variant, and must not be freed.</doc> + <source-position filename="ostree-core.h" line="370"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="variant" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1359">A #GVariant of type (su)</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="out_checksum" + direction="out" + caller-allocates="0" + transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1360">Pointer into string memory of @variant with checksum</doc> + <type name="utf8" c:type="const char**"/> + </parameter> + <parameter name="out_objtype" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1361">Return object type</doc> + <type name="ObjectType" c:type="OstreeObjectType*"/> + </parameter> + </parameters> + </function> + <function name="object_name_serialize" + c:identifier="ostree_object_name_serialize"> + <source-position filename="ostree-core.h" line="366"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1346">A new floating #GVariant containing checksum string and objtype</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </return-value> + <parameters> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1343">An ASCII checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1344">An object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + </parameters> + </function> + <function name="object_to_string" c:identifier="ostree_object_to_string"> + <source-position filename="ostree-core.h" line="375"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1278">A string containing both @checksum and a stringifed version of @objtype</doc> + <type name="utf8" c:type="char*"/> + </return-value> + <parameters> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1275">An ASCII checksum</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1276">Object type</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + </parameters> + </function> + <function name="object_type_from_string" + c:identifier="ostree_object_type_from_string"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1242">The reverse of ostree_object_type_to_string().</doc> + <source-position filename="ostree-core.h" line="360"/> + <return-value transfer-ownership="none"> + <type name="ObjectType" c:type="OstreeObjectType"/> + </return-value> + <parameters> + <parameter name="str" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1244">A stringified version of #OstreeObjectType</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="object_type_to_string" + c:identifier="ostree_object_type_to_string"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1207">Serialize @objtype to a string; this is used for file extensions.</doc> + <source-position filename="ostree-core.h" line="357"/> + <return-value transfer-ownership="none"> + <type name="utf8" c:type="const char*"/> + </return-value> + <parameters> + <parameter name="objtype" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="1209">an #OstreeObjectType</doc> + <type name="ObjectType" c:type="OstreeObjectType"/> + </parameter> + </parameters> + </function> + <docsection name="ostree-async-progress"> + <doc xml:space="preserve" + filename="ostree-async-progress.c" + line="26">For many asynchronous operations, it's desirable for callers to be +able to watch their status as they progress. For example, an user +interface calling an asynchronous download operation will want to +be able to see the total number of bytes downloaded. + +This class provides a mechanism for callees of asynchronous +operations to communicate back with callers. It transparently +handles thread safety, ensuring that the progress change +notification occurs in the thread-default context of the calling +operation. + +The ostree_async_progress_get_status() and ostree_async_progress_set_status() +methods get and set a well-known `status` key of type %G_VARIANT_TYPE_STRING. +This key may be accessed using the other #OstreeAsyncProgress methods, but it +must always have the correct type.</doc> + </docsection> + <docsection name="ostree-core"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="94">These functions implement repository-independent algorithms for +operating on the core OSTree data formats, such as converting +#GFileInfo into a #GVariant. + +There are 4 types of objects; file, dirmeta, tree, and commit. The +last 3 are metadata, and the file object is the only content object +type. + +All metadata objects are stored as #GVariant (big endian). The +rationale for this is the same as that of the ext{2,3,4} family of +filesystems; most developers will be using LE, and so it's better +to continually test the BE->LE swap. + +The file object is a custom format in order to support streaming.</doc> + </docsection> + <docsection name="ostree-gpg-verify-result"> + <doc xml:space="preserve" + filename="ostree-gpg-verify-result.c" + line="28">#OstreeGpgVerifyResult contains verification details for GPG signatures +read from a detached #OstreeRepo metadata object. + +Use ostree_gpg_verify_result_count_all() and +ostree_gpg_verify_result_count_valid() to quickly check overall signature +validity. + +Use ostree_gpg_verify_result_lookup() to find a signature by the key ID +or fingerprint of the signing key. + +For more in-depth inspection, such as presenting signature details to the +user, pass an array of attribute values to ostree_gpg_verify_result_get() +or get all signature details with ostree_gpg_verify_result_get_all().</doc> + </docsection> + <docsection name="ostree-lzma-compressor"> + <doc xml:space="preserve" + filename="ostree-lzma-compressor.c" + line="34">An implementation of #GConverter that compresses data using +LZMA.</doc> + </docsection> + <docsection name="ostree-lzma-decompressor"> + <doc xml:space="preserve" + filename="ostree-lzma-decompressor.c" + line="33">An implementation of #GConverter that decompresses data using +LZMA.</doc> + </docsection> + <docsection name="ostree-mutable-tree"> + <doc xml:space="preserve" + filename="ostree-mutable-tree.c" + line="29">In order to commit content into an #OstreeRepo, it must first be +imported into an #OstreeMutableTree. There are several high level +APIs to create an initiable #OstreeMutableTree from a physical +filesystem directory, but they may also be computed +programmatically.</doc> + </docsection> + <docsection name="ostree-repo"> + <doc xml:space="preserve" + filename="ostree-repo.c" + line="85">The #OstreeRepo is like git, a content-addressed object store. +Unlike git, it records uid, gid, and extended attributes. + +There are four possible "modes" for an #OstreeRepo; %OSTREE_REPO_MODE_BARE +is very simple - content files are represented exactly as they are, and +checkouts are just hardlinks. %OSTREE_REPO_MODE_BARE_USER is similar, except +the uid/gids are not set on the files, and checkouts as hardlinks work only +for user checkouts. %OSTREE_REPO_MODE_BARE_USER_ONLY is the same as +BARE_USER, but all metadata is not stored, so it can only be used for user +checkouts. This mode does not require xattrs. A %OSTREE_REPO_MODE_ARCHIVE +(also known as %OSTREE_REPO_MODE_ARCHIVE_Z2) repository in contrast stores +content files zlib-compressed. It is suitable for non-root-owned +repositories that can be served via a static HTTP server. + +Creating an #OstreeRepo does not invoke any file I/O, and thus needs +to be initialized, either from existing contents or as a new +repository. If you have an existing repo, use ostree_repo_open() +to load it from disk and check its validity. To initialize a new +repository in the given filepath, use ostree_repo_create() instead. + +To store content in the repo, first start a transaction with +ostree_repo_prepare_transaction(). Then create a +#OstreeMutableTree, and apply functions such as +ostree_repo_write_directory_to_mtree() to traverse a physical +filesystem and write content, possibly multiple times. + +Once the #OstreeMutableTree is complete, write all of its metadata +with ostree_repo_write_mtree(), and finally create a commit with +ostree_repo_write_commit(). + +## Collection IDs + +A collection ID is a globally unique identifier which, if set, is used to +identify refs from a repository which are mirrored elsewhere, such as in +mirror repositories or peer to peer networks. + +This is separate from the `collection-id` configuration key for a remote, which +is used to store the collection ID of the repository that remote points to. + +The collection ID should only be set on an #OstreeRepo if it is the canonical +collection for some refs. + +A collection ID must be a reverse DNS name, where the domain name is under the +control of the curator of the collection, so they can demonstrate ownership +of the collection. The later elements in the reverse DNS name can be used to +disambiguate between multiple collections from the same curator. For example, +`org.exampleos.Main` and `org.exampleos.Apps`. For the complete format of +collection IDs, see ostree_validate_collection_id().</doc> + </docsection> + <docsection name="ostree-repo-finder-avahi"> + <doc xml:space="preserve" + filename="ostree-repo-finder-avahi.c" + line="60">#OstreeRepoFinderAvahi is an implementation of #OstreeRepoFinder which looks +for refs being hosted by peers on the local network. + +Any ref which matches by collection ID and ref name is returned as a result, +with no limitations on the peers which host them, as long as they are +accessible over the local network, and their adverts reach this machine via +DNS-SD/mDNS. + +For each repository which is found, a result will be returned for the +intersection of the refs being searched for, and the refs in `refs/mirrors` +in the remote repository. + +DNS-SD resolution is performed using Avahi, which will continue to scan for +matching peers throughout the lifetime of the process. It’s recommended that +ostree_repo_finder_avahi_start() be called early on in the process’ lifetime, +and the #GMainContext which is passed to ostree_repo_finder_avahi_new() +continues to be iterated until ostree_repo_finder_avahi_stop() is called. + +The values stored in DNS-SD TXT records are stored as big-endian whenever +endianness is relevant. + +Internally, #OstreeRepoFinderAvahi has an Avahi client, browser and resolver +which work in the background to track all available peers on the local +network. Whenever a resolve request is made using +ostree_repo_finder_resolve_async(), the request is blocked until the +background tracking is in a consistent state (typically this only happens at +startup), and is then answered using the current cache of background data. +The Avahi client tracks the #OstreeRepoFinderAvahi’s connection with the +Avahi D-Bus service. The browser looks for DNS-SD peers on the local network; +and the resolver is used to retrieve information about services advertised by +each peer, including the services’ TXT records.</doc> + </docsection> + <docsection name="ostree-repo-finder-config"> + <doc xml:space="preserve" + filename="ostree-repo-finder-config.c" + line="38">#OstreeRepoFinderConfig is an implementation of #OstreeRepoFinder which looks +refs up in locally configured remotes and returns remote URIs. +Duplicate remote URIs are combined into a single #OstreeRepoFinderResult +which lists multiple refs. + +For all the locally configured remotes which have an `collection-id` specified +(see [ostree.repo-config(5)](man:ostree.repo-config(5))), it finds the +intersection of their refs and the set of refs to resolve. If the +intersection is non-empty, that remote is returned as a result. Remotes which +do not have their `collection-id` key configured are ignored.</doc> + </docsection> + <docsection name="ostree-repo-finder-mount"> + <doc xml:space="preserve" + filename="ostree-repo-finder-mount.c" + line="38">#OstreeRepoFinderMount is an implementation of #OstreeRepoFinder which looks +refs up in well-known locations on any mounted removable volumes. + +For each mounted removable volume, the directory `.ostree/repos.d` will be +enumerated, and all OSTree repositories below it will be searched, in lexical +order, for the requested #OstreeCollectionRefs. The names of the directories +below `.ostree/repos.d` are irrelevant, apart from their lexical ordering. +The directories `.ostree/repo`, `ostree/repo` and `var/lib/flatpak/repo` +will be searched after the others, if they exist. +Non-removable volumes are ignored. + +For each repository which is found, a result will be returned for the +intersection of the refs being searched for, and the refs in `refs/heads` and +`refs/mirrors` in the repository on the removable volume. + +Symlinks are followed when listing the repositories, so a volume might +contain a single OSTree at some arbitrary path, with a symlink from +`.ostree/repos.d`. Any symlink which points outside the volume’s file +system will be ignored. Repositories are deduplicated in the results. + +The volume monitor used to find mounted volumes can be overridden by setting +#OstreeRepoFinderMount:monitor. By default, g_volume_monitor_get() is used.</doc> + </docsection> + <docsection name="ostree-repo-finder-override"> + <doc xml:space="preserve" + filename="ostree-repo-finder-override.c" + line="38">#OstreeRepoFinderOverride is an implementation of #OstreeRepoFinder which +looks refs up in a list of remotes given by their URI, and returns the URIs +which contain the refs. Duplicate remote URIs are combined into a single +#OstreeRepoFinderResult which lists multiple refs. + +Each result is given an #OstreeRepoFinderResult.priority value of 20, which +ranks its results above those from the other default #OstreeRepoFinder +implementations. + +Results can only be returned for a ref if a remote and keyring are configured +locally for the collection ID of that ref, otherwise there would be no keys +available to verify signatures on commits for that ref. + +This is intended to be used for user-provided overrides and testing software +which uses #OstreeRepoFinder. For production use, #OstreeRepoFinderConfig is +recommended instead.</doc> + </docsection> + <docsection name="ostree-sepolicy"> + <doc xml:space="preserve" + filename="ostree-sepolicy.c" + line="35">A #OstreeSePolicy object can load the SELinux policy from a given +root and perform labeling.</doc> + </docsection> + <docsection name="ostree-sign"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="23">An #OstreeSign interface allows to select and use any available engine +for signing or verifying the commit object or summary file.</doc> + </docsection> + <docsection name="ostree-sysroot"> + <doc xml:space="preserve" + filename="ostree-sysroot.c" + line="39">A #OstreeSysroot object represents a physical root filesystem, +which in particular should contain a toplevel /ostree directory. +Inside this directory is an #OstreeRepo in /ostree/repo, plus a set +of deployments in /ostree/deploy. + +This class is not by default safe against concurrent use by threads +or external processes. You can use ostree_sysroot_lock() to +perform locking externally.</doc> + </docsection> + <docsection name="ostree-sysroot-upgrader"> + <doc xml:space="preserve" + filename="ostree-sysroot-upgrader.c" + line="28">The #OstreeSysrootUpgrader class allows performing simple upgrade +operations.</doc> + </docsection> + <docsection name="ostree-version"> + <doc xml:space="preserve" + filename="ostree-version.h" + line="20">ostree provides macros to check the version of the library +at compile-time</doc> + </docsection> + <function name="parse_refspec" + c:identifier="ostree_parse_refspec" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="154">Split a refspec like `gnome-ostree:gnome-ostree/buildmain` or just +`gnome-ostree/buildmain` into two parts. In the first case, @out_remote +will be set to `gnome-ostree`, and @out_ref to `gnome-ostree/buildmain`. +In the second case (a local ref), @out_remote will be %NULL, and @out_ref +will be `gnome-ostree/buildmain`. In both cases, %TRUE will be returned.</doc> + <source-position filename="ostree-core.h" line="351"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="168">%TRUE on successful parsing, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="refspec" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="156">A "refspec" string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + <parameter name="out_remote" + direction="out" + caller-allocates="0" + transfer-ownership="full" + nullable="1" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="157">Return location for the remote name, + or %NULL if the refspec refs to a local ref</doc> + <type name="utf8" c:type="char**"/> + </parameter> + <parameter name="out_ref" + direction="out" + caller-allocates="0" + transfer-ownership="full" + optional="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="159">Return location for the ref name</doc> + <type name="utf8" c:type="char**"/> + </parameter> + </parameters> + </function> + <function name="raw_file_to_archive_z2_stream" + c:identifier="ostree_raw_file_to_archive_z2_stream" + version="2016.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="459">Convert from a "bare" file representation into an +OSTREE_OBJECT_TYPE_FILE stream suitable for ostree pull.</doc> + <source-position filename="ostree-core.h" line="418"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="input" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="461">File raw content stream</doc> + <type name="Gio.InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="file_info" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="462">A file info</doc> + <type name="Gio.FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="xattrs" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="463">Optional extended attributes</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="out_input" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="464">Serialized object stream</doc> + <type name="Gio.InputStream" c:type="GInputStream**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="465">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="raw_file_to_archive_z2_stream_with_options" + c:identifier="ostree_raw_file_to_archive_z2_stream_with_options" + version="2017.3" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="486">Like ostree_raw_file_to_archive_z2_stream(), but supports an extensible set +of flags. The following flags are currently defined: + +- `compression-level` (`i`): Level of compression to use, 0–9, with 0 being + the least compression, and <0 giving the default level (currently 6).</doc> + <source-position filename="ostree-core.h" line="427"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="input" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="488">File raw content stream</doc> + <type name="Gio.InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="file_info" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="489">A file info</doc> + <type name="Gio.FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="xattrs" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="490">Optional extended attributes</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="options" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="491">A GVariant `a{sv}` with an extensible set of flags</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="out_input" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="492">Serialized object stream</doc> + <type name="Gio.InputStream" c:type="GInputStream**"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="493">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <function name="raw_file_to_content_stream" + c:identifier="ostree_raw_file_to_content_stream" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="526">Convert from a "bare" file representation into an +OSTREE_OBJECT_TYPE_FILE stream. This is a fundamental operation +for writing data to an #OstreeRepo.</doc> + <source-position filename="ostree-core.h" line="436"/> + <return-value transfer-ownership="none"> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="input" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="528">File raw content stream</doc> + <type name="Gio.InputStream" c:type="GInputStream*"/> + </parameter> + <parameter name="file_info" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="529">A file info</doc> + <type name="Gio.FileInfo" c:type="GFileInfo*"/> + </parameter> + <parameter name="xattrs" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="530">Optional extended attributes</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + <parameter name="out_input" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="531">Serialized object stream</doc> + <type name="Gio.InputStream" c:type="GInputStream**"/> + </parameter> + <parameter name="out_length" + direction="out" + caller-allocates="0" + transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="532">Length of stream</doc> + <type name="guint64" c:type="guint64*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="533">Cancellable</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + </parameters> + </function> + <docsection name="remote"> + <doc xml:space="preserve" + filename="ostree-remote.c" + line="38">The #OstreeRemote structure represents the configuration for a single remote +repository. Currently, all configuration is handled internally, and +#OstreeRemote objects are represented by their textual name handle, or by an +opaque pointer (which can be reference counted if needed). + +#OstreeRemote provides configuration for accessing a remote, but does not +provide the results of accessing a remote, such as information about what +refs are currently on a remote, or the commits they currently point to. Use +#OstreeRepo in combination with an #OstreeRemote to query that information.</doc> + </docsection> + <function name="repo_commit_traverse_iter_cleanup" + c:identifier="ostree_repo_commit_traverse_iter_cleanup" + moved-to="RepoCommitTraverseIter.cleanup"> + <source-position filename="ostree-repo.h" line="1256"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="p" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <type name="gpointer" c:type="void*"/> + </parameter> + </parameters> + </function> + <function name="repo_finder_resolve_all_async" + c:identifier="ostree_repo_finder_resolve_all_async" + moved-to="RepoFinder.resolve_all_async" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="243">A version of ostree_repo_finder_resolve_async() which queries one or more +@finders in parallel and combines the results.</doc> + <source-position filename="ostree-repo-finder.h" line="80"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="finders" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="245">non-empty array of #OstreeRepoFinders</doc> + <array c:type="OstreeRepoFinder* const*"> + <type name="RepoFinder" c:type="OstreeRepoFinder*"/> + </array> + </parameter> + <parameter name="refs" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="246">non-empty array of collection–ref pairs to find remotes for</doc> + <array c:type="const OstreeCollectionRef* const*"> + <type name="CollectionRef" c:type="OstreeCollectionRef*"/> + </array> + </parameter> + <parameter name="parent_repo" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="247">the local repository which the refs are being resolved for, + which provides configuration information and GPG keys</doc> + <type name="Repo" c:type="OstreeRepo*"/> + </parameter> + <parameter name="cancellable" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="249">a #GCancellable, or %NULL</doc> + <type name="Gio.Cancellable" c:type="GCancellable*"/> + </parameter> + <parameter name="callback" + transfer-ownership="none" + nullable="1" + allow-none="1" + scope="async" + closure="5"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="250">asynchronous completion callback</doc> + <type name="Gio.AsyncReadyCallback" c:type="GAsyncReadyCallback"/> + </parameter> + <parameter name="user_data" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="251">data to pass to @callback</doc> + <type name="gpointer" c:type="gpointer"/> + </parameter> + </parameters> + </function> + <function name="repo_finder_resolve_all_finish" + c:identifier="ostree_repo_finder_resolve_all_finish" + moved-to="RepoFinder.resolve_all_finish" + version="2018.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="404">Get the results from a ostree_repo_finder_resolve_all_async() operation.</doc> + <source-position filename="ostree-repo-finder.h" line="87"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="411">array of zero + or more results</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="RepoFinderResult"/> + </array> + </return-value> + <parameters> + <parameter name="result" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="406">#GAsyncResult from the callback</doc> + <type name="Gio.AsyncResult" c:type="GAsyncResult*"/> + </parameter> + </parameters> + </function> + <function name="repo_finder_result_freev" + c:identifier="ostree_repo_finder_result_freev" + moved-to="RepoFinderResult.freev" + version="2018.6"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="567">Free the given @results array, freeing each element and the container.</doc> + <source-position filename="ostree-repo-finder.h" line="184"/> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="results" transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-repo-finder.c" + line="569">an #OstreeRepoFinderResult</doc> + <array c:type="OstreeRepoFinderResult**"> + <type name="RepoFinderResult" c:type="OstreeRepoFinderResult*"/> + </array> + </parameter> + </parameters> + </function> + <function name="sign_get_all" + c:identifier="ostree_sign_get_all" + moved-to="Sign.get_all" + version="2020.2"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="518">Return an array with newly allocated instances of all available +signing engines; they will not be initialized.</doc> + <source-position filename="ostree-sign.h" line="159"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="524">an array of signing engines</doc> + <array name="GLib.PtrArray" c:type="GPtrArray*"> + <type name="Sign"/> + </array> + </return-value> + </function> + <function name="sign_get_by_name" + c:identifier="ostree_sign_get_by_name" + moved-to="Sign.get_by_name" + version="2020.2" + throws="1"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="542">Create a new instance of a signing engine.</doc> + <source-position filename="ostree-sign.h" line="162"/> + <return-value transfer-ownership="full"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="549">New signing engine, or %NULL if the engine is not known</doc> + <type name="Sign" c:type="OstreeSign*"/> + </return-value> + <parameters> + <parameter name="name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-sign.c" + line="544">the name of desired signature engine</doc> + <type name="utf8" c:type="const gchar*"/> + </parameter> + </parameters> + </function> + <function name="validate_checksum_string" + c:identifier="ostree_validate_checksum_string" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="131">Use this function to see if input strings are checksums.</doc> + <source-position filename="ostree-core.h" line="301"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="138">%TRUE if @sha256 is a valid checksum string, %FALSE otherwise</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="sha256" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="133">SHA256 hex string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="validate_collection_id" + c:identifier="ostree_validate_collection_id" + version="2018.6" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="284">Check whether the given @collection_id is valid. Return an error if it is +invalid or %NULL. + +Valid collection IDs are reverse DNS names: + * They 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]_` and must not + begin with a digit. + * They must contain at least one `.` (period) character (and thus at least two elements). + * They must not begin with a `.` (period) character. + * They must not exceed 255 characters in length. + +(This makes their format identical to D-Bus interface names, for consistency.)</doc> + <source-position filename="ostree-core.h" line="345"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="303">%TRUE if @collection_id is a valid collection ID, %FALSE if it is invalid + or %NULL</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="collection_id" + transfer-ownership="none" + nullable="1" + allow-none="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="286">A collection ID</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="validate_remote_name" + c:identifier="ostree_validate_remote_name" + version="2017.8" + throws="1"> + <source-position filename="ostree-core.h" line="348"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="260">%TRUE if @remote_name is a valid remote name</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="remote_name" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="257">A remote name</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="validate_rev" + c:identifier="ostree_validate_rev" + throws="1"> + <source-position filename="ostree-core.h" line="342"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="232">%TRUE if @rev is a valid ref string</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="rev" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="229">A revision string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="validate_structureof_checksum_string" + c:identifier="ostree_validate_structureof_checksum_string" + throws="1"> + <source-position filename="ostree-core.h" line="525"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2070">%TRUE if @checksum is a valid ASCII SHA256 checksum</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2067">an ASCII string</doc> + <type name="utf8" c:type="const char*"/> + </parameter> + </parameters> + </function> + <function name="validate_structureof_commit" + c:identifier="ostree_validate_structureof_commit" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2194">Use this to validate the basic structure of @commit, independent of +any other objects it references.</doc> + <source-position filename="ostree-core.h" line="533"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2202">%TRUE if @commit is structurally valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="commit" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2196">A commit object, %OSTREE_OBJECT_TYPE_COMMIT</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <function name="validate_structureof_csum_v" + c:identifier="ostree_validate_structureof_csum_v" + throws="1"> + <source-position filename="ostree-core.h" line="521"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2056">%TRUE if @checksum is a valid binary SHA256 checksum</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="checksum" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2053">a #GVariant of type "ay"</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <function name="validate_structureof_dirmeta" + c:identifier="ostree_validate_structureof_dirmeta" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2359">Use this to validate the basic structure of @dirmeta.</doc> + <source-position filename="ostree-core.h" line="541"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2366">%TRUE if @dirmeta is structurally valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="dirmeta" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2361">A dirmeta object, %OSTREE_OBJECT_TYPE_DIR_META</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <function name="validate_structureof_dirtree" + c:identifier="ostree_validate_structureof_dirtree" + throws="1"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2247">Use this to validate the basic structure of @dirtree, independent of +any other objects it references.</doc> + <source-position filename="ostree-core.h" line="537"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2255">%TRUE if @dirtree is structurally valid</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="dirtree" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2249">A dirtree object, %OSTREE_OBJECT_TYPE_DIR_TREE</doc> + <type name="GLib.Variant" c:type="GVariant*"/> + </parameter> + </parameters> + </function> + <function name="validate_structureof_file_mode" + c:identifier="ostree_validate_structureof_file_mode" + throws="1"> + <source-position filename="ostree-core.h" line="529"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2344">%TRUE if @mode represents a valid file type and permissions</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="mode" transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2341">A Unix filesystem mode</doc> + <type name="guint32" c:type="guint32"/> + </parameter> + </parameters> + </function> + <function name="validate_structureof_objtype" + c:identifier="ostree_validate_structureof_objtype" + throws="1"> + <source-position filename="ostree-core.h" line="517"/> + <return-value transfer-ownership="none"> + <doc xml:space="preserve" + filename="ostree-core.c" + line="2038">%TRUE if @objtype represents a valid object type</doc> + <type name="gboolean" c:type="gboolean"/> + </return-value> + <parameters> + <parameter name="objtype" transfer-ownership="none"> + <type name="guint8" c:type="guchar"/> + </parameter> + </parameters> + </function> + </namespace> +</repository> diff --git a/rust-bindings/src/.gitattributes b/rust-bindings/src/.gitattributes new file mode 100644 index 0000000000..5b781ce7bc --- /dev/null +++ b/rust-bindings/src/.gitattributes @@ -0,0 +1 @@ +auto/** linguist-generated=true diff --git a/rust-bindings/src/auto/async_progress.rs b/rust-bindings/src/auto/async_progress.rs new file mode 100644 index 0000000000..f6040441d8 --- /dev/null +++ b/rust-bindings/src/auto/async_progress.rs @@ -0,0 +1,157 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use glib::object::ObjectType as ObjectType_; +use glib::signal::connect_raw; +use glib::signal::SignalHandlerId; +use glib::translate::*; +use std::boxed::Box as Box_; +use std::fmt; +use std::mem::transmute; + +glib::wrapper! { + #[doc(alias = "OstreeAsyncProgress")] + pub struct AsyncProgress(Object<ffi::OstreeAsyncProgress, ffi::OstreeAsyncProgressClass>); + + match fn { + type_ => || ffi::ostree_async_progress_get_type(), + } +} + +impl AsyncProgress { + #[doc(alias = "ostree_async_progress_new")] + pub fn new() -> AsyncProgress { + unsafe { + from_glib_full(ffi::ostree_async_progress_new()) + } + } + + //#[doc(alias = "ostree_async_progress_new_and_connect")] + //pub fn new_and_connect(changed: /*Unimplemented*/Option<Fundamental: Pointer>, user_data: /*Unimplemented*/Option<Fundamental: Pointer>) -> AsyncProgress { + // unsafe { TODO: call ffi:ostree_async_progress_new_and_connect() } + //} + + #[cfg(any(feature = "v2019_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_6")))] + #[doc(alias = "ostree_async_progress_copy_state")] + pub fn copy_state(&self, dest: &AsyncProgress) { + unsafe { + ffi::ostree_async_progress_copy_state(self.to_glib_none().0, dest.to_glib_none().0); + } + } + + #[doc(alias = "ostree_async_progress_finish")] + pub fn finish(&self) { + unsafe { + ffi::ostree_async_progress_finish(self.to_glib_none().0); + } + } + + //#[cfg(any(feature = "v2017_6", feature = "dox"))] + //#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_6")))] + //#[doc(alias = "ostree_async_progress_get")] + //pub fn get(&self, : /*Unknown conversion*//*Unimplemented*/Fundamental: VarArgs) { + // unsafe { TODO: call ffi:ostree_async_progress_get() } + //} + + #[cfg(any(feature = "v2017_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_6")))] + #[doc(alias = "ostree_async_progress_get_status")] + #[doc(alias = "get_status")] + pub fn status(&self) -> Option<glib::GString> { + unsafe { + from_glib_full(ffi::ostree_async_progress_get_status(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_async_progress_get_uint")] + #[doc(alias = "get_uint")] + pub fn uint(&self, key: &str) -> u32 { + unsafe { + ffi::ostree_async_progress_get_uint(self.to_glib_none().0, key.to_glib_none().0) + } + } + + #[doc(alias = "ostree_async_progress_get_uint64")] + #[doc(alias = "get_uint64")] + pub fn uint64(&self, key: &str) -> u64 { + unsafe { + ffi::ostree_async_progress_get_uint64(self.to_glib_none().0, key.to_glib_none().0) + } + } + + #[cfg(any(feature = "v2017_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_6")))] + #[doc(alias = "ostree_async_progress_get_variant")] + #[doc(alias = "get_variant")] + pub fn variant(&self, key: &str) -> Option<glib::Variant> { + unsafe { + from_glib_full(ffi::ostree_async_progress_get_variant(self.to_glib_none().0, key.to_glib_none().0)) + } + } + + //#[cfg(any(feature = "v2017_6", feature = "dox"))] + //#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_6")))] + //#[doc(alias = "ostree_async_progress_set")] + //pub fn set(&self, : /*Unknown conversion*//*Unimplemented*/Fundamental: VarArgs) { + // unsafe { TODO: call ffi:ostree_async_progress_set() } + //} + + #[cfg(any(feature = "v2017_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_6")))] + #[doc(alias = "ostree_async_progress_set_status")] + pub fn set_status(&self, status: Option<&str>) { + unsafe { + ffi::ostree_async_progress_set_status(self.to_glib_none().0, status.to_glib_none().0); + } + } + + #[doc(alias = "ostree_async_progress_set_uint")] + pub fn set_uint(&self, key: &str, value: u32) { + unsafe { + ffi::ostree_async_progress_set_uint(self.to_glib_none().0, key.to_glib_none().0, value); + } + } + + #[doc(alias = "ostree_async_progress_set_uint64")] + pub fn set_uint64(&self, key: &str, value: u64) { + unsafe { + ffi::ostree_async_progress_set_uint64(self.to_glib_none().0, key.to_glib_none().0, value); + } + } + + #[cfg(any(feature = "v2017_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_6")))] + #[doc(alias = "ostree_async_progress_set_variant")] + pub fn set_variant(&self, key: &str, value: &glib::Variant) { + unsafe { + ffi::ostree_async_progress_set_variant(self.to_glib_none().0, key.to_glib_none().0, value.to_glib_none().0); + } + } + + #[doc(alias = "changed")] + pub fn connect_changed<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn changed_trampoline<F: Fn(&AsyncProgress) + 'static>(this: *mut ffi::OstreeAsyncProgress, f: glib::ffi::gpointer) { + let f: &F = &*(f as *const F); + f(&from_glib_borrow(this)) + } + unsafe { + let f: Box_<F> = Box_::new(f); + connect_raw(self.as_ptr() as *mut _, b"changed\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>(changed_trampoline::<F> as *const ())), Box_::into_raw(f)) + } + } +} + +impl Default for AsyncProgress { + fn default() -> Self { + Self::new() + } +} + +impl fmt::Display for AsyncProgress { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("AsyncProgress") + } +} diff --git a/rust-bindings/src/auto/bootconfig_parser.rs b/rust-bindings/src/auto/bootconfig_parser.rs new file mode 100644 index 0000000000..a19a4127bd --- /dev/null +++ b/rust-bindings/src/auto/bootconfig_parser.rs @@ -0,0 +1,114 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use glib::object::IsA; +use glib::translate::*; +use std::fmt; +use std::ptr; + +glib::wrapper! { + #[doc(alias = "OstreeBootconfigParser")] + pub struct BootconfigParser(Object<ffi::OstreeBootconfigParser>); + + match fn { + type_ => || ffi::ostree_bootconfig_parser_get_type(), + } +} + +impl BootconfigParser { + #[doc(alias = "ostree_bootconfig_parser_new")] + pub fn new() -> BootconfigParser { + unsafe { + from_glib_full(ffi::ostree_bootconfig_parser_new()) + } + } + + #[doc(alias = "ostree_bootconfig_parser_clone")] + pub fn clone(&self) -> Option<BootconfigParser> { + unsafe { + from_glib_full(ffi::ostree_bootconfig_parser_clone(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_bootconfig_parser_get")] + pub fn get(&self, key: &str) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_bootconfig_parser_get(self.to_glib_none().0, key.to_glib_none().0)) + } + } + + #[cfg(any(feature = "v2020_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_7")))] + #[doc(alias = "ostree_bootconfig_parser_get_overlay_initrds")] + #[doc(alias = "get_overlay_initrds")] + pub fn overlay_initrds(&self) -> Vec<glib::GString> { + unsafe { + FromGlibPtrContainer::from_glib_none(ffi::ostree_bootconfig_parser_get_overlay_initrds(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_bootconfig_parser_parse")] + pub fn parse<P: IsA<gio::File>, Q: IsA<gio::Cancellable>>(&self, path: &P, cancellable: Option<&Q>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_bootconfig_parser_parse(self.to_glib_none().0, path.as_ref().to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_bootconfig_parser_parse_at")] + pub fn parse_at<P: IsA<gio::Cancellable>>(&self, dfd: i32, path: &str, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_bootconfig_parser_parse_at(self.to_glib_none().0, dfd, path.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_bootconfig_parser_set")] + pub fn set(&self, key: &str, value: &str) { + unsafe { + ffi::ostree_bootconfig_parser_set(self.to_glib_none().0, key.to_glib_none().0, value.to_glib_none().0); + } + } + + #[cfg(any(feature = "v2020_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_7")))] + #[doc(alias = "ostree_bootconfig_parser_set_overlay_initrds")] + pub fn set_overlay_initrds(&self, initrds: &[&str]) { + unsafe { + ffi::ostree_bootconfig_parser_set_overlay_initrds(self.to_glib_none().0, initrds.to_glib_none().0); + } + } + + #[doc(alias = "ostree_bootconfig_parser_write")] + pub fn write<P: IsA<gio::File>, Q: IsA<gio::Cancellable>>(&self, output: &P, cancellable: Option<&Q>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_bootconfig_parser_write(self.to_glib_none().0, output.as_ref().to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_bootconfig_parser_write_at")] + pub fn write_at<P: IsA<gio::Cancellable>>(&self, dfd: i32, path: &str, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_bootconfig_parser_write_at(self.to_glib_none().0, dfd, path.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } +} + +impl Default for BootconfigParser { + fn default() -> Self { + Self::new() + } +} + +impl fmt::Display for BootconfigParser { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("BootconfigParser") + } +} diff --git a/rust-bindings/src/auto/collection_ref.rs b/rust-bindings/src/auto/collection_ref.rs new file mode 100644 index 0000000000..c6f8cd4cf6 --- /dev/null +++ b/rust-bindings/src/auto/collection_ref.rs @@ -0,0 +1,56 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use glib::translate::*; +use std::hash; + +glib::wrapper! { + #[derive(Debug, PartialOrd, Ord)] + pub struct CollectionRef(Boxed<ffi::OstreeCollectionRef>); + + match fn { + copy => |ptr| glib::gobject_ffi::g_boxed_copy(ffi::ostree_collection_ref_get_type(), ptr as *mut _) as *mut ffi::OstreeCollectionRef, + free => |ptr| glib::gobject_ffi::g_boxed_free(ffi::ostree_collection_ref_get_type(), ptr as *mut _), + type_ => || ffi::ostree_collection_ref_get_type(), + } +} + +impl CollectionRef { + #[doc(alias = "ostree_collection_ref_new")] + pub fn new(collection_id: Option<&str>, ref_name: &str) -> Option<CollectionRef> { + unsafe { + from_glib_full(ffi::ostree_collection_ref_new(collection_id.to_glib_none().0, ref_name.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_collection_ref_equal")] + fn equal(&self, ref2: &CollectionRef) -> bool { + unsafe { + from_glib(ffi::ostree_collection_ref_equal(ToGlibPtr::<*const ffi::OstreeCollectionRef>::to_glib_none(self).0 as glib::ffi::gconstpointer, ToGlibPtr::<*const ffi::OstreeCollectionRef>::to_glib_none(ref2).0 as glib::ffi::gconstpointer)) + } + } + + #[doc(alias = "ostree_collection_ref_hash")] + fn hash(&self) -> u32 { + unsafe { + ffi::ostree_collection_ref_hash(ToGlibPtr::<*const ffi::OstreeCollectionRef>::to_glib_none(self).0 as glib::ffi::gconstpointer) + } + } +} + +impl PartialEq for CollectionRef { + #[inline] + fn eq(&self, other: &Self) -> bool { + self.equal(other) + } +} + +impl Eq for CollectionRef {} + +impl hash::Hash for CollectionRef { + #[inline] + fn hash<H>(&self, state: &mut H) where H: hash::Hasher { + hash::Hash::hash(&self.hash(), state) + } +} diff --git a/rust-bindings/src/auto/commit_sizes_entry.rs b/rust-bindings/src/auto/commit_sizes_entry.rs new file mode 100644 index 0000000000..c52ecc5c6e --- /dev/null +++ b/rust-bindings/src/auto/commit_sizes_entry.rs @@ -0,0 +1,26 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use crate::ObjectType; +use glib::translate::*; + +glib::wrapper! { + #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] + pub struct CommitSizesEntry(Boxed<ffi::OstreeCommitSizesEntry>); + + match fn { + copy => |ptr| ffi::ostree_commit_sizes_entry_copy(ptr), + free => |ptr| ffi::ostree_commit_sizes_entry_free(ptr), + type_ => || ffi::ostree_commit_sizes_entry_get_type(), + } +} + +impl CommitSizesEntry { + #[doc(alias = "ostree_commit_sizes_entry_new")] + pub fn new(checksum: &str, objtype: ObjectType, unpacked: u64, archived: u64) -> Option<CommitSizesEntry> { + unsafe { + from_glib_full(ffi::ostree_commit_sizes_entry_new(checksum.to_glib_none().0, objtype.into_glib(), unpacked, archived)) + } + } +} diff --git a/rust-bindings/src/auto/constants.rs b/rust-bindings/src/auto/constants.rs new file mode 100644 index 0000000000..396d5c85a1 --- /dev/null +++ b/rust-bindings/src/auto/constants.rs @@ -0,0 +1,76 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use std::ffi::CStr; + +#[doc(alias = "OSTREE_COMMIT_GVARIANT_STRING")] +pub static COMMIT_GVARIANT_STRING: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_COMMIT_GVARIANT_STRING).to_str().unwrap()}); +#[cfg(any(feature = "v2020_4", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_4")))] +#[doc(alias = "OSTREE_COMMIT_META_KEY_ARCHITECTURE")] +pub static COMMIT_META_KEY_ARCHITECTURE: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_COMMIT_META_KEY_ARCHITECTURE).to_str().unwrap()}); +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +#[doc(alias = "OSTREE_COMMIT_META_KEY_COLLECTION_BINDING")] +pub static COMMIT_META_KEY_COLLECTION_BINDING: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_COMMIT_META_KEY_COLLECTION_BINDING).to_str().unwrap()}); +#[cfg(any(feature = "v2017_7", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_7")))] +#[doc(alias = "OSTREE_COMMIT_META_KEY_ENDOFLIFE")] +pub static COMMIT_META_KEY_ENDOFLIFE: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_COMMIT_META_KEY_ENDOFLIFE).to_str().unwrap()}); +#[cfg(any(feature = "v2017_7", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_7")))] +#[doc(alias = "OSTREE_COMMIT_META_KEY_ENDOFLIFE_REBASE")] +pub static COMMIT_META_KEY_ENDOFLIFE_REBASE: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_COMMIT_META_KEY_ENDOFLIFE_REBASE).to_str().unwrap()}); +#[cfg(any(feature = "v2017_9", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_9")))] +#[doc(alias = "OSTREE_COMMIT_META_KEY_REF_BINDING")] +pub static COMMIT_META_KEY_REF_BINDING: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_COMMIT_META_KEY_REF_BINDING).to_str().unwrap()}); +#[cfg(any(feature = "v2017_13", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_13")))] +#[doc(alias = "OSTREE_COMMIT_META_KEY_SOURCE_TITLE")] +pub static COMMIT_META_KEY_SOURCE_TITLE: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_COMMIT_META_KEY_SOURCE_TITLE).to_str().unwrap()}); +#[cfg(any(feature = "v2014_9", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2014_9")))] +#[doc(alias = "OSTREE_COMMIT_META_KEY_VERSION")] +pub static COMMIT_META_KEY_VERSION: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_COMMIT_META_KEY_VERSION).to_str().unwrap()}); +#[doc(alias = "OSTREE_DIRMETA_GVARIANT_STRING")] +pub static DIRMETA_GVARIANT_STRING: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_DIRMETA_GVARIANT_STRING).to_str().unwrap()}); +#[doc(alias = "OSTREE_FILEMETA_GVARIANT_STRING")] +pub static FILEMETA_GVARIANT_STRING: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_FILEMETA_GVARIANT_STRING).to_str().unwrap()}); +#[doc(alias = "OSTREE_GPG_KEY_GVARIANT_STRING")] +pub static GPG_KEY_GVARIANT_STRING: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_GPG_KEY_GVARIANT_STRING).to_str().unwrap()}); +#[cfg(any(feature = "v2021_1", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_1")))] +#[doc(alias = "OSTREE_METADATA_KEY_BOOTABLE")] +pub static METADATA_KEY_BOOTABLE: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_METADATA_KEY_BOOTABLE).to_str().unwrap()}); +#[cfg(any(feature = "v2021_1", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_1")))] +#[doc(alias = "OSTREE_METADATA_KEY_LINUX")] +pub static METADATA_KEY_LINUX: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_METADATA_KEY_LINUX).to_str().unwrap()}); +#[cfg(any(feature = "v2018_9", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_9")))] +#[doc(alias = "OSTREE_META_KEY_DEPLOY_COLLECTION_ID")] +pub static META_KEY_DEPLOY_COLLECTION_ID: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_META_KEY_DEPLOY_COLLECTION_ID).to_str().unwrap()}); +#[cfg(any(feature = "v2018_3", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_3")))] +#[doc(alias = "OSTREE_ORIGIN_TRANSIENT_GROUP")] +pub static ORIGIN_TRANSIENT_GROUP: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_ORIGIN_TRANSIENT_GROUP).to_str().unwrap()}); +#[cfg(any(feature = "v2022_2", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2022_2")))] +#[doc(alias = "OSTREE_PATH_BOOTED")] +pub static PATH_BOOTED: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_PATH_BOOTED).to_str().unwrap()}); +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +#[doc(alias = "OSTREE_REPO_METADATA_REF")] +pub static REPO_METADATA_REF: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_REPO_METADATA_REF).to_str().unwrap()}); +#[cfg(any(feature = "v2020_4", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_4")))] +#[doc(alias = "OSTREE_SIGN_NAME_ED25519")] +pub static SIGN_NAME_ED25519: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_SIGN_NAME_ED25519).to_str().unwrap()}); +#[doc(alias = "OSTREE_SUMMARY_GVARIANT_STRING")] +pub static SUMMARY_GVARIANT_STRING: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_SUMMARY_GVARIANT_STRING).to_str().unwrap()}); +#[doc(alias = "OSTREE_SUMMARY_SIG_GVARIANT_STRING")] +pub static SUMMARY_SIG_GVARIANT_STRING: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_SUMMARY_SIG_GVARIANT_STRING).to_str().unwrap()}); +#[doc(alias = "OSTREE_TREE_GVARIANT_STRING")] +pub static TREE_GVARIANT_STRING: once_cell::sync::Lazy<&'static str> = once_cell::sync::Lazy::new(|| unsafe{CStr::from_ptr(ffi::OSTREE_TREE_GVARIANT_STRING).to_str().unwrap()}); diff --git a/rust-bindings/src/auto/content_writer.rs b/rust-bindings/src/auto/content_writer.rs new file mode 100644 index 0000000000..5631e00276 --- /dev/null +++ b/rust-bindings/src/auto/content_writer.rs @@ -0,0 +1,34 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use glib::object::IsA; +use glib::translate::*; +use std::fmt; +use std::ptr; + +glib::wrapper! { + #[doc(alias = "OstreeContentWriter")] + pub struct ContentWriter(Object<ffi::OstreeContentWriter, ffi::OstreeContentWriterClass>) @extends gio::OutputStream; + + match fn { + type_ => || ffi::ostree_content_writer_get_type(), + } +} + +impl ContentWriter { + #[doc(alias = "ostree_content_writer_finish")] + pub fn finish<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<glib::GString, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_content_writer_finish(self.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } +} + +impl fmt::Display for ContentWriter { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("ContentWriter") + } +} diff --git a/rust-bindings/src/auto/deployment.rs b/rust-bindings/src/auto/deployment.rs new file mode 100644 index 0000000000..3dddaf5398 --- /dev/null +++ b/rust-bindings/src/auto/deployment.rs @@ -0,0 +1,201 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use crate::BootconfigParser; +#[cfg(any(feature = "v2016_4", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] +use crate::DeploymentUnlockedState; +use glib::translate::*; +use std::fmt; + +glib::wrapper! { + #[doc(alias = "OstreeDeployment")] + pub struct Deployment(Object<ffi::OstreeDeployment>); + + match fn { + type_ => || ffi::ostree_deployment_get_type(), + } +} + +impl Deployment { + #[doc(alias = "ostree_deployment_new")] + pub fn new(index: i32, osname: &str, csum: &str, deployserial: i32, bootcsum: Option<&str>, bootserial: i32) -> Deployment { + unsafe { + from_glib_full(ffi::ostree_deployment_new(index, osname.to_glib_none().0, csum.to_glib_none().0, deployserial, bootcsum.to_glib_none().0, bootserial)) + } + } + + #[doc(alias = "ostree_deployment_clone")] + pub fn clone(&self) -> Option<Deployment> { + unsafe { + from_glib_full(ffi::ostree_deployment_clone(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_deployment_equal")] + pub fn equal(&self, bp: &Deployment) -> bool { + unsafe { + from_glib(ffi::ostree_deployment_equal(ToGlibPtr::<*mut ffi::OstreeDeployment>::to_glib_none(self).0 as glib::ffi::gconstpointer, ToGlibPtr::<*mut ffi::OstreeDeployment>::to_glib_none(bp).0 as glib::ffi::gconstpointer)) + } + } + + #[doc(alias = "ostree_deployment_get_bootconfig")] + #[doc(alias = "get_bootconfig")] + pub fn bootconfig(&self) -> Option<BootconfigParser> { + unsafe { + from_glib_none(ffi::ostree_deployment_get_bootconfig(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_deployment_get_bootcsum")] + #[doc(alias = "get_bootcsum")] + pub fn bootcsum(&self) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_deployment_get_bootcsum(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_deployment_get_bootserial")] + #[doc(alias = "get_bootserial")] + pub fn bootserial(&self) -> i32 { + unsafe { + ffi::ostree_deployment_get_bootserial(self.to_glib_none().0) + } + } + + #[doc(alias = "ostree_deployment_get_csum")] + #[doc(alias = "get_csum")] + pub fn csum(&self) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_deployment_get_csum(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_deployment_get_deployserial")] + #[doc(alias = "get_deployserial")] + pub fn deployserial(&self) -> i32 { + unsafe { + ffi::ostree_deployment_get_deployserial(self.to_glib_none().0) + } + } + + #[doc(alias = "ostree_deployment_get_index")] + #[doc(alias = "get_index")] + pub fn index(&self) -> i32 { + unsafe { + ffi::ostree_deployment_get_index(self.to_glib_none().0) + } + } + + #[doc(alias = "ostree_deployment_get_origin")] + #[doc(alias = "get_origin")] + pub fn origin(&self) -> Option<glib::KeyFile> { + unsafe { + from_glib_none(ffi::ostree_deployment_get_origin(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_deployment_get_origin_relpath")] + #[doc(alias = "get_origin_relpath")] + pub fn origin_relpath(&self) -> Option<glib::GString> { + unsafe { + from_glib_full(ffi::ostree_deployment_get_origin_relpath(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_deployment_get_osname")] + #[doc(alias = "get_osname")] + pub fn osname(&self) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_deployment_get_osname(self.to_glib_none().0)) + } + } + + #[cfg(any(feature = "v2016_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] + #[doc(alias = "ostree_deployment_get_unlocked")] + #[doc(alias = "get_unlocked")] + pub fn unlocked(&self) -> DeploymentUnlockedState { + unsafe { + from_glib(ffi::ostree_deployment_get_unlocked(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_deployment_hash")] + pub fn hash(&self) -> u32 { + unsafe { + ffi::ostree_deployment_hash(ToGlibPtr::<*mut ffi::OstreeDeployment>::to_glib_none(self).0 as glib::ffi::gconstpointer) + } + } + + #[cfg(any(feature = "v2018_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_3")))] + #[doc(alias = "ostree_deployment_is_pinned")] + pub fn is_pinned(&self) -> bool { + unsafe { + from_glib(ffi::ostree_deployment_is_pinned(self.to_glib_none().0)) + } + } + + #[cfg(any(feature = "v2018_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_3")))] + #[doc(alias = "ostree_deployment_is_staged")] + pub fn is_staged(&self) -> bool { + unsafe { + from_glib(ffi::ostree_deployment_is_staged(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_deployment_set_bootconfig")] + pub fn set_bootconfig(&self, bootconfig: Option<&BootconfigParser>) { + unsafe { + ffi::ostree_deployment_set_bootconfig(self.to_glib_none().0, bootconfig.to_glib_none().0); + } + } + + #[doc(alias = "ostree_deployment_set_bootserial")] + pub fn set_bootserial(&self, index: i32) { + unsafe { + ffi::ostree_deployment_set_bootserial(self.to_glib_none().0, index); + } + } + + #[doc(alias = "ostree_deployment_set_index")] + pub fn set_index(&self, index: i32) { + unsafe { + ffi::ostree_deployment_set_index(self.to_glib_none().0, index); + } + } + + #[doc(alias = "ostree_deployment_set_origin")] + pub fn set_origin(&self, origin: Option<&glib::KeyFile>) { + unsafe { + ffi::ostree_deployment_set_origin(self.to_glib_none().0, origin.to_glib_none().0); + } + } + + #[cfg(any(feature = "v2018_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_3")))] + #[doc(alias = "ostree_deployment_origin_remove_transient_state")] + pub fn origin_remove_transient_state(origin: &glib::KeyFile) { + unsafe { + ffi::ostree_deployment_origin_remove_transient_state(origin.to_glib_none().0); + } + } + + #[cfg(any(feature = "v2016_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] + #[doc(alias = "ostree_deployment_unlocked_state_to_string")] + pub fn unlocked_state_to_string(state: DeploymentUnlockedState) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_deployment_unlocked_state_to_string(state.into_glib())) + } + } +} + +impl fmt::Display for Deployment { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("Deployment") + } +} diff --git a/rust-bindings/src/auto/diff_item.rs b/rust-bindings/src/auto/diff_item.rs new file mode 100644 index 0000000000..7320367f8f --- /dev/null +++ b/rust-bindings/src/auto/diff_item.rs @@ -0,0 +1,15 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + + +glib::wrapper! { + #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] + pub struct DiffItem(Shared<ffi::OstreeDiffItem>); + + match fn { + ref => |ptr| ffi::ostree_diff_item_ref(ptr), + unref => |ptr| ffi::ostree_diff_item_unref(ptr), + type_ => || ffi::ostree_diff_item_get_type(), + } +} diff --git a/rust-bindings/src/auto/enums.rs b/rust-bindings/src/auto/enums.rs new file mode 100644 index 0000000000..2eecdb9752 --- /dev/null +++ b/rust-bindings/src/auto/enums.rs @@ -0,0 +1,692 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use glib::translate::*; +use std::fmt; + +#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash)] +#[derive(Clone, Copy)] +#[non_exhaustive] +#[doc(alias = "OstreeDeploymentUnlockedState")] +pub enum DeploymentUnlockedState { + #[doc(alias = "OSTREE_DEPLOYMENT_UNLOCKED_NONE")] + None, + #[doc(alias = "OSTREE_DEPLOYMENT_UNLOCKED_DEVELOPMENT")] + Development, + #[doc(alias = "OSTREE_DEPLOYMENT_UNLOCKED_HOTFIX")] + Hotfix, + #[doc(alias = "OSTREE_DEPLOYMENT_UNLOCKED_TRANSIENT")] + Transient, +#[doc(hidden)] + __Unknown(i32), +} + +impl fmt::Display for DeploymentUnlockedState { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "DeploymentUnlockedState::{}", match *self { + Self::None => "None", + Self::Development => "Development", + Self::Hotfix => "Hotfix", + Self::Transient => "Transient", + _ => "Unknown", + }) + } +} + +#[doc(hidden)] +impl IntoGlib for DeploymentUnlockedState { + type GlibType = ffi::OstreeDeploymentUnlockedState; + + fn into_glib(self) -> ffi::OstreeDeploymentUnlockedState { + match self { + Self::None => ffi::OSTREE_DEPLOYMENT_UNLOCKED_NONE, + Self::Development => ffi::OSTREE_DEPLOYMENT_UNLOCKED_DEVELOPMENT, + Self::Hotfix => ffi::OSTREE_DEPLOYMENT_UNLOCKED_HOTFIX, + Self::Transient => ffi::OSTREE_DEPLOYMENT_UNLOCKED_TRANSIENT, + Self::__Unknown(value) => value, +} + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeDeploymentUnlockedState> for DeploymentUnlockedState { + unsafe fn from_glib(value: ffi::OstreeDeploymentUnlockedState) -> Self { + match value { + ffi::OSTREE_DEPLOYMENT_UNLOCKED_NONE => Self::None, + ffi::OSTREE_DEPLOYMENT_UNLOCKED_DEVELOPMENT => Self::Development, + ffi::OSTREE_DEPLOYMENT_UNLOCKED_HOTFIX => Self::Hotfix, + ffi::OSTREE_DEPLOYMENT_UNLOCKED_TRANSIENT => Self::Transient, + value => Self::__Unknown(value), +} + } +} + +#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash)] +#[derive(Clone, Copy)] +#[non_exhaustive] +#[doc(alias = "OstreeGpgSignatureAttr")] +pub enum GpgSignatureAttr { + #[doc(alias = "OSTREE_GPG_SIGNATURE_ATTR_VALID")] + Valid, + #[doc(alias = "OSTREE_GPG_SIGNATURE_ATTR_SIG_EXPIRED")] + SigExpired, + #[doc(alias = "OSTREE_GPG_SIGNATURE_ATTR_KEY_EXPIRED")] + KeyExpired, + #[doc(alias = "OSTREE_GPG_SIGNATURE_ATTR_KEY_REVOKED")] + KeyRevoked, + #[doc(alias = "OSTREE_GPG_SIGNATURE_ATTR_KEY_MISSING")] + KeyMissing, + #[doc(alias = "OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT")] + Fingerprint, + #[doc(alias = "OSTREE_GPG_SIGNATURE_ATTR_TIMESTAMP")] + Timestamp, + #[doc(alias = "OSTREE_GPG_SIGNATURE_ATTR_EXP_TIMESTAMP")] + ExpTimestamp, + #[doc(alias = "OSTREE_GPG_SIGNATURE_ATTR_PUBKEY_ALGO_NAME")] + PubkeyAlgoName, + #[doc(alias = "OSTREE_GPG_SIGNATURE_ATTR_HASH_ALGO_NAME")] + HashAlgoName, + #[doc(alias = "OSTREE_GPG_SIGNATURE_ATTR_USER_NAME")] + UserName, + #[doc(alias = "OSTREE_GPG_SIGNATURE_ATTR_USER_EMAIL")] + UserEmail, + #[doc(alias = "OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT_PRIMARY")] + FingerprintPrimary, + #[doc(alias = "OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP")] + KeyExpTimestamp, + #[doc(alias = "OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP_PRIMARY")] + KeyExpTimestampPrimary, +#[doc(hidden)] + __Unknown(i32), +} + +impl fmt::Display for GpgSignatureAttr { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "GpgSignatureAttr::{}", match *self { + Self::Valid => "Valid", + Self::SigExpired => "SigExpired", + Self::KeyExpired => "KeyExpired", + Self::KeyRevoked => "KeyRevoked", + Self::KeyMissing => "KeyMissing", + Self::Fingerprint => "Fingerprint", + Self::Timestamp => "Timestamp", + Self::ExpTimestamp => "ExpTimestamp", + Self::PubkeyAlgoName => "PubkeyAlgoName", + Self::HashAlgoName => "HashAlgoName", + Self::UserName => "UserName", + Self::UserEmail => "UserEmail", + Self::FingerprintPrimary => "FingerprintPrimary", + Self::KeyExpTimestamp => "KeyExpTimestamp", + Self::KeyExpTimestampPrimary => "KeyExpTimestampPrimary", + _ => "Unknown", + }) + } +} + +#[doc(hidden)] +impl IntoGlib for GpgSignatureAttr { + type GlibType = ffi::OstreeGpgSignatureAttr; + + fn into_glib(self) -> ffi::OstreeGpgSignatureAttr { + match self { + Self::Valid => ffi::OSTREE_GPG_SIGNATURE_ATTR_VALID, + Self::SigExpired => ffi::OSTREE_GPG_SIGNATURE_ATTR_SIG_EXPIRED, + Self::KeyExpired => ffi::OSTREE_GPG_SIGNATURE_ATTR_KEY_EXPIRED, + Self::KeyRevoked => ffi::OSTREE_GPG_SIGNATURE_ATTR_KEY_REVOKED, + Self::KeyMissing => ffi::OSTREE_GPG_SIGNATURE_ATTR_KEY_MISSING, + Self::Fingerprint => ffi::OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT, + Self::Timestamp => ffi::OSTREE_GPG_SIGNATURE_ATTR_TIMESTAMP, + Self::ExpTimestamp => ffi::OSTREE_GPG_SIGNATURE_ATTR_EXP_TIMESTAMP, + Self::PubkeyAlgoName => ffi::OSTREE_GPG_SIGNATURE_ATTR_PUBKEY_ALGO_NAME, + Self::HashAlgoName => ffi::OSTREE_GPG_SIGNATURE_ATTR_HASH_ALGO_NAME, + Self::UserName => ffi::OSTREE_GPG_SIGNATURE_ATTR_USER_NAME, + Self::UserEmail => ffi::OSTREE_GPG_SIGNATURE_ATTR_USER_EMAIL, + Self::FingerprintPrimary => ffi::OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT_PRIMARY, + Self::KeyExpTimestamp => ffi::OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP, + Self::KeyExpTimestampPrimary => ffi::OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP_PRIMARY, + Self::__Unknown(value) => value, +} + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeGpgSignatureAttr> for GpgSignatureAttr { + unsafe fn from_glib(value: ffi::OstreeGpgSignatureAttr) -> Self { + match value { + ffi::OSTREE_GPG_SIGNATURE_ATTR_VALID => Self::Valid, + ffi::OSTREE_GPG_SIGNATURE_ATTR_SIG_EXPIRED => Self::SigExpired, + ffi::OSTREE_GPG_SIGNATURE_ATTR_KEY_EXPIRED => Self::KeyExpired, + ffi::OSTREE_GPG_SIGNATURE_ATTR_KEY_REVOKED => Self::KeyRevoked, + ffi::OSTREE_GPG_SIGNATURE_ATTR_KEY_MISSING => Self::KeyMissing, + ffi::OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT => Self::Fingerprint, + ffi::OSTREE_GPG_SIGNATURE_ATTR_TIMESTAMP => Self::Timestamp, + ffi::OSTREE_GPG_SIGNATURE_ATTR_EXP_TIMESTAMP => Self::ExpTimestamp, + ffi::OSTREE_GPG_SIGNATURE_ATTR_PUBKEY_ALGO_NAME => Self::PubkeyAlgoName, + ffi::OSTREE_GPG_SIGNATURE_ATTR_HASH_ALGO_NAME => Self::HashAlgoName, + ffi::OSTREE_GPG_SIGNATURE_ATTR_USER_NAME => Self::UserName, + ffi::OSTREE_GPG_SIGNATURE_ATTR_USER_EMAIL => Self::UserEmail, + ffi::OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT_PRIMARY => Self::FingerprintPrimary, + ffi::OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP => Self::KeyExpTimestamp, + ffi::OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP_PRIMARY => Self::KeyExpTimestampPrimary, + value => Self::__Unknown(value), +} + } +} + +#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash)] +#[derive(Clone, Copy)] +#[non_exhaustive] +#[doc(alias = "OstreeObjectType")] +pub enum ObjectType { + #[doc(alias = "OSTREE_OBJECT_TYPE_FILE")] + File, + #[doc(alias = "OSTREE_OBJECT_TYPE_DIR_TREE")] + DirTree, + #[doc(alias = "OSTREE_OBJECT_TYPE_DIR_META")] + DirMeta, + #[doc(alias = "OSTREE_OBJECT_TYPE_COMMIT")] + Commit, + #[doc(alias = "OSTREE_OBJECT_TYPE_TOMBSTONE_COMMIT")] + TombstoneCommit, + #[doc(alias = "OSTREE_OBJECT_TYPE_COMMIT_META")] + CommitMeta, + #[doc(alias = "OSTREE_OBJECT_TYPE_PAYLOAD_LINK")] + PayloadLink, + #[doc(alias = "OSTREE_OBJECT_TYPE_FILE_XATTRS")] + FileXattrs, + #[doc(alias = "OSTREE_OBJECT_TYPE_FILE_XATTRS_LINK")] + FileXattrsLink, +#[doc(hidden)] + __Unknown(i32), +} + +impl fmt::Display for ObjectType { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "ObjectType::{}", match *self { + Self::File => "File", + Self::DirTree => "DirTree", + Self::DirMeta => "DirMeta", + Self::Commit => "Commit", + Self::TombstoneCommit => "TombstoneCommit", + Self::CommitMeta => "CommitMeta", + Self::PayloadLink => "PayloadLink", + Self::FileXattrs => "FileXattrs", + Self::FileXattrsLink => "FileXattrsLink", + _ => "Unknown", + }) + } +} + +#[doc(hidden)] +impl IntoGlib for ObjectType { + type GlibType = ffi::OstreeObjectType; + + fn into_glib(self) -> ffi::OstreeObjectType { + match self { + Self::File => ffi::OSTREE_OBJECT_TYPE_FILE, + Self::DirTree => ffi::OSTREE_OBJECT_TYPE_DIR_TREE, + Self::DirMeta => ffi::OSTREE_OBJECT_TYPE_DIR_META, + Self::Commit => ffi::OSTREE_OBJECT_TYPE_COMMIT, + Self::TombstoneCommit => ffi::OSTREE_OBJECT_TYPE_TOMBSTONE_COMMIT, + Self::CommitMeta => ffi::OSTREE_OBJECT_TYPE_COMMIT_META, + Self::PayloadLink => ffi::OSTREE_OBJECT_TYPE_PAYLOAD_LINK, + Self::FileXattrs => ffi::OSTREE_OBJECT_TYPE_FILE_XATTRS, + Self::FileXattrsLink => ffi::OSTREE_OBJECT_TYPE_FILE_XATTRS_LINK, + Self::__Unknown(value) => value, +} + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeObjectType> for ObjectType { + unsafe fn from_glib(value: ffi::OstreeObjectType) -> Self { + match value { + ffi::OSTREE_OBJECT_TYPE_FILE => Self::File, + ffi::OSTREE_OBJECT_TYPE_DIR_TREE => Self::DirTree, + ffi::OSTREE_OBJECT_TYPE_DIR_META => Self::DirMeta, + ffi::OSTREE_OBJECT_TYPE_COMMIT => Self::Commit, + ffi::OSTREE_OBJECT_TYPE_TOMBSTONE_COMMIT => Self::TombstoneCommit, + ffi::OSTREE_OBJECT_TYPE_COMMIT_META => Self::CommitMeta, + ffi::OSTREE_OBJECT_TYPE_PAYLOAD_LINK => Self::PayloadLink, + ffi::OSTREE_OBJECT_TYPE_FILE_XATTRS => Self::FileXattrs, + ffi::OSTREE_OBJECT_TYPE_FILE_XATTRS_LINK => Self::FileXattrsLink, + value => Self::__Unknown(value), +} + } +} + +#[cfg(any(feature = "v2018_2", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_2")))] +#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash)] +#[derive(Clone, Copy)] +#[non_exhaustive] +#[doc(alias = "OstreeRepoCheckoutFilterResult")] +pub enum RepoCheckoutFilterResult { + #[doc(alias = "OSTREE_REPO_CHECKOUT_FILTER_ALLOW")] + Allow, + #[doc(alias = "OSTREE_REPO_CHECKOUT_FILTER_SKIP")] + Skip, +#[doc(hidden)] + __Unknown(i32), +} + +#[cfg(any(feature = "v2018_2", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_2")))] +impl fmt::Display for RepoCheckoutFilterResult { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "RepoCheckoutFilterResult::{}", match *self { + Self::Allow => "Allow", + Self::Skip => "Skip", + _ => "Unknown", + }) + } +} + +#[cfg(any(feature = "v2018_2", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_2")))] +#[doc(hidden)] +impl IntoGlib for RepoCheckoutFilterResult { + type GlibType = ffi::OstreeRepoCheckoutFilterResult; + + fn into_glib(self) -> ffi::OstreeRepoCheckoutFilterResult { + match self { + Self::Allow => ffi::OSTREE_REPO_CHECKOUT_FILTER_ALLOW, + Self::Skip => ffi::OSTREE_REPO_CHECKOUT_FILTER_SKIP, + Self::__Unknown(value) => value, +} + } +} + +#[cfg(any(feature = "v2018_2", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_2")))] +#[doc(hidden)] +impl FromGlib<ffi::OstreeRepoCheckoutFilterResult> for RepoCheckoutFilterResult { + unsafe fn from_glib(value: ffi::OstreeRepoCheckoutFilterResult) -> Self { + match value { + ffi::OSTREE_REPO_CHECKOUT_FILTER_ALLOW => Self::Allow, + ffi::OSTREE_REPO_CHECKOUT_FILTER_SKIP => Self::Skip, + value => Self::__Unknown(value), +} + } +} + +#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash)] +#[derive(Clone, Copy)] +#[non_exhaustive] +#[doc(alias = "OstreeRepoCheckoutMode")] +pub enum RepoCheckoutMode { + #[doc(alias = "OSTREE_REPO_CHECKOUT_MODE_NONE")] + None, + #[doc(alias = "OSTREE_REPO_CHECKOUT_MODE_USER")] + User, +#[doc(hidden)] + __Unknown(i32), +} + +impl fmt::Display for RepoCheckoutMode { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "RepoCheckoutMode::{}", match *self { + Self::None => "None", + Self::User => "User", + _ => "Unknown", + }) + } +} + +#[doc(hidden)] +impl IntoGlib for RepoCheckoutMode { + type GlibType = ffi::OstreeRepoCheckoutMode; + + fn into_glib(self) -> ffi::OstreeRepoCheckoutMode { + match self { + Self::None => ffi::OSTREE_REPO_CHECKOUT_MODE_NONE, + Self::User => ffi::OSTREE_REPO_CHECKOUT_MODE_USER, + Self::__Unknown(value) => value, +} + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeRepoCheckoutMode> for RepoCheckoutMode { + unsafe fn from_glib(value: ffi::OstreeRepoCheckoutMode) -> Self { + match value { + ffi::OSTREE_REPO_CHECKOUT_MODE_NONE => Self::None, + ffi::OSTREE_REPO_CHECKOUT_MODE_USER => Self::User, + value => Self::__Unknown(value), +} + } +} + +#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash)] +#[derive(Clone, Copy)] +#[non_exhaustive] +#[doc(alias = "OstreeRepoCheckoutOverwriteMode")] +pub enum RepoCheckoutOverwriteMode { + #[doc(alias = "OSTREE_REPO_CHECKOUT_OVERWRITE_NONE")] + None, + #[doc(alias = "OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_FILES")] + UnionFiles, + #[doc(alias = "OSTREE_REPO_CHECKOUT_OVERWRITE_ADD_FILES")] + AddFiles, + #[doc(alias = "OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_IDENTICAL")] + UnionIdentical, +#[doc(hidden)] + __Unknown(i32), +} + +impl fmt::Display for RepoCheckoutOverwriteMode { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "RepoCheckoutOverwriteMode::{}", match *self { + Self::None => "None", + Self::UnionFiles => "UnionFiles", + Self::AddFiles => "AddFiles", + Self::UnionIdentical => "UnionIdentical", + _ => "Unknown", + }) + } +} + +#[doc(hidden)] +impl IntoGlib for RepoCheckoutOverwriteMode { + type GlibType = ffi::OstreeRepoCheckoutOverwriteMode; + + fn into_glib(self) -> ffi::OstreeRepoCheckoutOverwriteMode { + match self { + Self::None => ffi::OSTREE_REPO_CHECKOUT_OVERWRITE_NONE, + Self::UnionFiles => ffi::OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_FILES, + Self::AddFiles => ffi::OSTREE_REPO_CHECKOUT_OVERWRITE_ADD_FILES, + Self::UnionIdentical => ffi::OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_IDENTICAL, + Self::__Unknown(value) => value, +} + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeRepoCheckoutOverwriteMode> for RepoCheckoutOverwriteMode { + unsafe fn from_glib(value: ffi::OstreeRepoCheckoutOverwriteMode) -> Self { + match value { + ffi::OSTREE_REPO_CHECKOUT_OVERWRITE_NONE => Self::None, + ffi::OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_FILES => Self::UnionFiles, + ffi::OSTREE_REPO_CHECKOUT_OVERWRITE_ADD_FILES => Self::AddFiles, + ffi::OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_IDENTICAL => Self::UnionIdentical, + value => Self::__Unknown(value), +} + } +} + +#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash)] +#[derive(Clone, Copy)] +#[non_exhaustive] +#[doc(alias = "OstreeRepoCommitFilterResult")] +pub enum RepoCommitFilterResult { + #[doc(alias = "OSTREE_REPO_COMMIT_FILTER_ALLOW")] + Allow, + #[doc(alias = "OSTREE_REPO_COMMIT_FILTER_SKIP")] + Skip, +#[doc(hidden)] + __Unknown(i32), +} + +impl fmt::Display for RepoCommitFilterResult { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "RepoCommitFilterResult::{}", match *self { + Self::Allow => "Allow", + Self::Skip => "Skip", + _ => "Unknown", + }) + } +} + +#[doc(hidden)] +impl IntoGlib for RepoCommitFilterResult { + type GlibType = ffi::OstreeRepoCommitFilterResult; + + fn into_glib(self) -> ffi::OstreeRepoCommitFilterResult { + match self { + Self::Allow => ffi::OSTREE_REPO_COMMIT_FILTER_ALLOW, + Self::Skip => ffi::OSTREE_REPO_COMMIT_FILTER_SKIP, + Self::__Unknown(value) => value, +} + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeRepoCommitFilterResult> for RepoCommitFilterResult { + unsafe fn from_glib(value: ffi::OstreeRepoCommitFilterResult) -> Self { + match value { + ffi::OSTREE_REPO_COMMIT_FILTER_ALLOW => Self::Allow, + ffi::OSTREE_REPO_COMMIT_FILTER_SKIP => Self::Skip, + value => Self::__Unknown(value), +} + } +} + +#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash)] +#[derive(Clone, Copy)] +#[non_exhaustive] +#[doc(alias = "OstreeRepoCommitIterResult")] +pub enum RepoCommitIterResult { + #[doc(alias = "OSTREE_REPO_COMMIT_ITER_RESULT_ERROR")] + Error, + #[doc(alias = "OSTREE_REPO_COMMIT_ITER_RESULT_END")] + End, + #[doc(alias = "OSTREE_REPO_COMMIT_ITER_RESULT_FILE")] + File, + #[doc(alias = "OSTREE_REPO_COMMIT_ITER_RESULT_DIR")] + Dir, +#[doc(hidden)] + __Unknown(i32), +} + +impl fmt::Display for RepoCommitIterResult { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "RepoCommitIterResult::{}", match *self { + Self::Error => "Error", + Self::End => "End", + Self::File => "File", + Self::Dir => "Dir", + _ => "Unknown", + }) + } +} + +#[doc(hidden)] +impl IntoGlib for RepoCommitIterResult { + type GlibType = ffi::OstreeRepoCommitIterResult; + + fn into_glib(self) -> ffi::OstreeRepoCommitIterResult { + match self { + Self::Error => ffi::OSTREE_REPO_COMMIT_ITER_RESULT_ERROR, + Self::End => ffi::OSTREE_REPO_COMMIT_ITER_RESULT_END, + Self::File => ffi::OSTREE_REPO_COMMIT_ITER_RESULT_FILE, + Self::Dir => ffi::OSTREE_REPO_COMMIT_ITER_RESULT_DIR, + Self::__Unknown(value) => value, +} + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeRepoCommitIterResult> for RepoCommitIterResult { + unsafe fn from_glib(value: ffi::OstreeRepoCommitIterResult) -> Self { + match value { + ffi::OSTREE_REPO_COMMIT_ITER_RESULT_ERROR => Self::Error, + ffi::OSTREE_REPO_COMMIT_ITER_RESULT_END => Self::End, + ffi::OSTREE_REPO_COMMIT_ITER_RESULT_FILE => Self::File, + ffi::OSTREE_REPO_COMMIT_ITER_RESULT_DIR => Self::Dir, + value => Self::__Unknown(value), +} + } +} + +#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash)] +#[derive(Clone, Copy)] +#[non_exhaustive] +#[doc(alias = "OstreeRepoMode")] +pub enum RepoMode { + #[doc(alias = "OSTREE_REPO_MODE_BARE")] + Bare, + #[doc(alias = "OSTREE_REPO_MODE_ARCHIVE")] + Archive, + #[doc(alias = "OSTREE_REPO_MODE_BARE_USER")] + BareUser, + #[doc(alias = "OSTREE_REPO_MODE_BARE_USER_ONLY")] + BareUserOnly, + #[doc(alias = "OSTREE_REPO_MODE_BARE_SPLIT_XATTRS")] + BareSplitXattrs, +#[doc(hidden)] + __Unknown(i32), +} + +impl fmt::Display for RepoMode { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "RepoMode::{}", match *self { + Self::Bare => "Bare", + Self::Archive => "Archive", + Self::BareUser => "BareUser", + Self::BareUserOnly => "BareUserOnly", + Self::BareSplitXattrs => "BareSplitXattrs", + _ => "Unknown", + }) + } +} + +#[doc(hidden)] +impl IntoGlib for RepoMode { + type GlibType = ffi::OstreeRepoMode; + + fn into_glib(self) -> ffi::OstreeRepoMode { + match self { + Self::Bare => ffi::OSTREE_REPO_MODE_BARE, + Self::Archive => ffi::OSTREE_REPO_MODE_ARCHIVE, + Self::BareUser => ffi::OSTREE_REPO_MODE_BARE_USER, + Self::BareUserOnly => ffi::OSTREE_REPO_MODE_BARE_USER_ONLY, + Self::BareSplitXattrs => ffi::OSTREE_REPO_MODE_BARE_SPLIT_XATTRS, + Self::__Unknown(value) => value, +} + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeRepoMode> for RepoMode { + unsafe fn from_glib(value: ffi::OstreeRepoMode) -> Self { + match value { + ffi::OSTREE_REPO_MODE_BARE => Self::Bare, + ffi::OSTREE_REPO_MODE_ARCHIVE => Self::Archive, + ffi::OSTREE_REPO_MODE_BARE_USER => Self::BareUser, + ffi::OSTREE_REPO_MODE_BARE_USER_ONLY => Self::BareUserOnly, + ffi::OSTREE_REPO_MODE_BARE_SPLIT_XATTRS => Self::BareSplitXattrs, + value => Self::__Unknown(value), +} + } +} + +#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash)] +#[derive(Clone, Copy)] +#[non_exhaustive] +#[doc(alias = "OstreeRepoRemoteChange")] +pub enum RepoRemoteChange { + #[doc(alias = "OSTREE_REPO_REMOTE_CHANGE_ADD")] + Add, + #[doc(alias = "OSTREE_REPO_REMOTE_CHANGE_ADD_IF_NOT_EXISTS")] + AddIfNotExists, + #[doc(alias = "OSTREE_REPO_REMOTE_CHANGE_DELETE")] + Delete, + #[doc(alias = "OSTREE_REPO_REMOTE_CHANGE_DELETE_IF_EXISTS")] + DeleteIfExists, + #[doc(alias = "OSTREE_REPO_REMOTE_CHANGE_REPLACE")] + Replace, +#[doc(hidden)] + __Unknown(i32), +} + +impl fmt::Display for RepoRemoteChange { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "RepoRemoteChange::{}", match *self { + Self::Add => "Add", + Self::AddIfNotExists => "AddIfNotExists", + Self::Delete => "Delete", + Self::DeleteIfExists => "DeleteIfExists", + Self::Replace => "Replace", + _ => "Unknown", + }) + } +} + +#[doc(hidden)] +impl IntoGlib for RepoRemoteChange { + type GlibType = ffi::OstreeRepoRemoteChange; + + fn into_glib(self) -> ffi::OstreeRepoRemoteChange { + match self { + Self::Add => ffi::OSTREE_REPO_REMOTE_CHANGE_ADD, + Self::AddIfNotExists => ffi::OSTREE_REPO_REMOTE_CHANGE_ADD_IF_NOT_EXISTS, + Self::Delete => ffi::OSTREE_REPO_REMOTE_CHANGE_DELETE, + Self::DeleteIfExists => ffi::OSTREE_REPO_REMOTE_CHANGE_DELETE_IF_EXISTS, + Self::Replace => ffi::OSTREE_REPO_REMOTE_CHANGE_REPLACE, + Self::__Unknown(value) => value, +} + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeRepoRemoteChange> for RepoRemoteChange { + unsafe fn from_glib(value: ffi::OstreeRepoRemoteChange) -> Self { + match value { + ffi::OSTREE_REPO_REMOTE_CHANGE_ADD => Self::Add, + ffi::OSTREE_REPO_REMOTE_CHANGE_ADD_IF_NOT_EXISTS => Self::AddIfNotExists, + ffi::OSTREE_REPO_REMOTE_CHANGE_DELETE => Self::Delete, + ffi::OSTREE_REPO_REMOTE_CHANGE_DELETE_IF_EXISTS => Self::DeleteIfExists, + ffi::OSTREE_REPO_REMOTE_CHANGE_REPLACE => Self::Replace, + value => Self::__Unknown(value), +} + } +} + +#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash)] +#[derive(Clone, Copy)] +#[non_exhaustive] +#[doc(alias = "OstreeStaticDeltaGenerateOpt")] +pub enum StaticDeltaGenerateOpt { + #[doc(alias = "OSTREE_STATIC_DELTA_GENERATE_OPT_LOWLATENCY")] + Lowlatency, + #[doc(alias = "OSTREE_STATIC_DELTA_GENERATE_OPT_MAJOR")] + Major, +#[doc(hidden)] + __Unknown(i32), +} + +impl fmt::Display for StaticDeltaGenerateOpt { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "StaticDeltaGenerateOpt::{}", match *self { + Self::Lowlatency => "Lowlatency", + Self::Major => "Major", + _ => "Unknown", + }) + } +} + +#[doc(hidden)] +impl IntoGlib for StaticDeltaGenerateOpt { + type GlibType = ffi::OstreeStaticDeltaGenerateOpt; + + fn into_glib(self) -> ffi::OstreeStaticDeltaGenerateOpt { + match self { + Self::Lowlatency => ffi::OSTREE_STATIC_DELTA_GENERATE_OPT_LOWLATENCY, + Self::Major => ffi::OSTREE_STATIC_DELTA_GENERATE_OPT_MAJOR, + Self::__Unknown(value) => value, +} + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeStaticDeltaGenerateOpt> for StaticDeltaGenerateOpt { + unsafe fn from_glib(value: ffi::OstreeStaticDeltaGenerateOpt) -> Self { + match value { + ffi::OSTREE_STATIC_DELTA_GENERATE_OPT_LOWLATENCY => Self::Lowlatency, + ffi::OSTREE_STATIC_DELTA_GENERATE_OPT_MAJOR => Self::Major, + value => Self::__Unknown(value), +} + } +} + diff --git a/rust-bindings/src/auto/flags.rs b/rust-bindings/src/auto/flags.rs new file mode 100644 index 0000000000..0a08e5f766 --- /dev/null +++ b/rust-bindings/src/auto/flags.rs @@ -0,0 +1,626 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use bitflags::bitflags; +use glib::translate::*; +use glib::value::FromValue; +use glib::value::ToValue; +use glib::StaticType; +use glib::Type; +use std::fmt; + +#[cfg(any(feature = "v2017_13", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_13")))] +bitflags! { + #[doc(alias = "OstreeChecksumFlags")] + pub struct ChecksumFlags: u32 { + #[doc(alias = "OSTREE_CHECKSUM_FLAGS_NONE")] + const NONE = ffi::OSTREE_CHECKSUM_FLAGS_NONE as u32; + #[doc(alias = "OSTREE_CHECKSUM_FLAGS_IGNORE_XATTRS")] + const IGNORE_XATTRS = ffi::OSTREE_CHECKSUM_FLAGS_IGNORE_XATTRS as u32; + #[doc(alias = "OSTREE_CHECKSUM_FLAGS_CANONICAL_PERMISSIONS")] + const CANONICAL_PERMISSIONS = ffi::OSTREE_CHECKSUM_FLAGS_CANONICAL_PERMISSIONS as u32; + } +} + +#[cfg(any(feature = "v2017_13", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_13")))] +impl fmt::Display for ChecksumFlags { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + <Self as fmt::Debug>::fmt(self, f) + } +} + +#[cfg(any(feature = "v2017_13", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_13")))] +#[doc(hidden)] +impl IntoGlib for ChecksumFlags { + type GlibType = ffi::OstreeChecksumFlags; + + fn into_glib(self) -> ffi::OstreeChecksumFlags { + self.bits() + } +} + +#[cfg(any(feature = "v2017_13", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_13")))] +#[doc(hidden)] +impl FromGlib<ffi::OstreeChecksumFlags> for ChecksumFlags { + unsafe fn from_glib(value: ffi::OstreeChecksumFlags) -> Self { + Self::from_bits_truncate(value) + } +} + +bitflags! { + #[doc(alias = "OstreeDiffFlags")] + pub struct DiffFlags: u32 { + #[doc(alias = "OSTREE_DIFF_FLAGS_NONE")] + const NONE = ffi::OSTREE_DIFF_FLAGS_NONE as u32; + #[doc(alias = "OSTREE_DIFF_FLAGS_IGNORE_XATTRS")] + const IGNORE_XATTRS = ffi::OSTREE_DIFF_FLAGS_IGNORE_XATTRS as u32; + } +} + +impl fmt::Display for DiffFlags { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + <Self as fmt::Debug>::fmt(self, f) + } +} + +#[doc(hidden)] +impl IntoGlib for DiffFlags { + type GlibType = ffi::OstreeDiffFlags; + + fn into_glib(self) -> ffi::OstreeDiffFlags { + self.bits() + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeDiffFlags> for DiffFlags { + unsafe fn from_glib(value: ffi::OstreeDiffFlags) -> Self { + Self::from_bits_truncate(value) + } +} + +bitflags! { + #[doc(alias = "OstreeGpgSignatureFormatFlags")] + pub struct GpgSignatureFormatFlags: u32 { + #[doc(alias = "OSTREE_GPG_SIGNATURE_FORMAT_DEFAULT")] + const GPG_SIGNATURE_FORMAT_DEFAULT = ffi::OSTREE_GPG_SIGNATURE_FORMAT_DEFAULT as u32; + } +} + +impl fmt::Display for GpgSignatureFormatFlags { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + <Self as fmt::Debug>::fmt(self, f) + } +} + +#[doc(hidden)] +impl IntoGlib for GpgSignatureFormatFlags { + type GlibType = ffi::OstreeGpgSignatureFormatFlags; + + fn into_glib(self) -> ffi::OstreeGpgSignatureFormatFlags { + self.bits() + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeGpgSignatureFormatFlags> for GpgSignatureFormatFlags { + unsafe fn from_glib(value: ffi::OstreeGpgSignatureFormatFlags) -> Self { + Self::from_bits_truncate(value) + } +} + +bitflags! { + #[doc(alias = "OstreeRepoCommitModifierFlags")] + pub struct RepoCommitModifierFlags: u32 { + #[doc(alias = "OSTREE_REPO_COMMIT_MODIFIER_FLAGS_NONE")] + const NONE = ffi::OSTREE_REPO_COMMIT_MODIFIER_FLAGS_NONE as u32; + #[doc(alias = "OSTREE_REPO_COMMIT_MODIFIER_FLAGS_SKIP_XATTRS")] + const SKIP_XATTRS = ffi::OSTREE_REPO_COMMIT_MODIFIER_FLAGS_SKIP_XATTRS as u32; + #[doc(alias = "OSTREE_REPO_COMMIT_MODIFIER_FLAGS_GENERATE_SIZES")] + const GENERATE_SIZES = ffi::OSTREE_REPO_COMMIT_MODIFIER_FLAGS_GENERATE_SIZES as u32; + #[doc(alias = "OSTREE_REPO_COMMIT_MODIFIER_FLAGS_CANONICAL_PERMISSIONS")] + const CANONICAL_PERMISSIONS = ffi::OSTREE_REPO_COMMIT_MODIFIER_FLAGS_CANONICAL_PERMISSIONS as u32; + #[doc(alias = "OSTREE_REPO_COMMIT_MODIFIER_FLAGS_ERROR_ON_UNLABELED")] + const ERROR_ON_UNLABELED = ffi::OSTREE_REPO_COMMIT_MODIFIER_FLAGS_ERROR_ON_UNLABELED as u32; + #[doc(alias = "OSTREE_REPO_COMMIT_MODIFIER_FLAGS_CONSUME")] + const CONSUME = ffi::OSTREE_REPO_COMMIT_MODIFIER_FLAGS_CONSUME as u32; + #[doc(alias = "OSTREE_REPO_COMMIT_MODIFIER_FLAGS_DEVINO_CANONICAL")] + const DEVINO_CANONICAL = ffi::OSTREE_REPO_COMMIT_MODIFIER_FLAGS_DEVINO_CANONICAL as u32; + } +} + +impl fmt::Display for RepoCommitModifierFlags { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + <Self as fmt::Debug>::fmt(self, f) + } +} + +#[doc(hidden)] +impl IntoGlib for RepoCommitModifierFlags { + type GlibType = ffi::OstreeRepoCommitModifierFlags; + + fn into_glib(self) -> ffi::OstreeRepoCommitModifierFlags { + self.bits() + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeRepoCommitModifierFlags> for RepoCommitModifierFlags { + unsafe fn from_glib(value: ffi::OstreeRepoCommitModifierFlags) -> Self { + Self::from_bits_truncate(value) + } +} + +#[cfg(any(feature = "v2015_7", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2015_7")))] +bitflags! { + #[doc(alias = "OstreeRepoCommitState")] + pub struct RepoCommitState: u32 { + #[doc(alias = "OSTREE_REPO_COMMIT_STATE_NORMAL")] + const NORMAL = ffi::OSTREE_REPO_COMMIT_STATE_NORMAL as u32; + #[doc(alias = "OSTREE_REPO_COMMIT_STATE_PARTIAL")] + const PARTIAL = ffi::OSTREE_REPO_COMMIT_STATE_PARTIAL as u32; + #[doc(alias = "OSTREE_REPO_COMMIT_STATE_FSCK_PARTIAL")] + const FSCK_PARTIAL = ffi::OSTREE_REPO_COMMIT_STATE_FSCK_PARTIAL as u32; + } +} + +#[cfg(any(feature = "v2015_7", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2015_7")))] +impl fmt::Display for RepoCommitState { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + <Self as fmt::Debug>::fmt(self, f) + } +} + +#[cfg(any(feature = "v2015_7", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2015_7")))] +#[doc(hidden)] +impl IntoGlib for RepoCommitState { + type GlibType = ffi::OstreeRepoCommitState; + + fn into_glib(self) -> ffi::OstreeRepoCommitState { + self.bits() + } +} + +#[cfg(any(feature = "v2015_7", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2015_7")))] +#[doc(hidden)] +impl FromGlib<ffi::OstreeRepoCommitState> for RepoCommitState { + unsafe fn from_glib(value: ffi::OstreeRepoCommitState) -> Self { + Self::from_bits_truncate(value) + } +} + +bitflags! { + #[doc(alias = "OstreeRepoCommitTraverseFlags")] + pub struct RepoCommitTraverseFlags: u32 { + #[doc(alias = "OSTREE_REPO_COMMIT_TRAVERSE_FLAG_NONE")] + const NONE = ffi::OSTREE_REPO_COMMIT_TRAVERSE_FLAG_NONE as u32; + #[doc(alias = "OSTREE_REPO_COMMIT_TRAVERSE_FLAG_COMMIT_ONLY")] + const COMMIT_ONLY = ffi::OSTREE_REPO_COMMIT_TRAVERSE_FLAG_COMMIT_ONLY as u32; + } +} + +impl fmt::Display for RepoCommitTraverseFlags { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + <Self as fmt::Debug>::fmt(self, f) + } +} + +#[doc(hidden)] +impl IntoGlib for RepoCommitTraverseFlags { + type GlibType = ffi::OstreeRepoCommitTraverseFlags; + + fn into_glib(self) -> ffi::OstreeRepoCommitTraverseFlags { + self.bits() + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeRepoCommitTraverseFlags> for RepoCommitTraverseFlags { + unsafe fn from_glib(value: ffi::OstreeRepoCommitTraverseFlags) -> Self { + Self::from_bits_truncate(value) + } +} + +bitflags! { + #[doc(alias = "OstreeRepoListObjectsFlags")] + pub struct RepoListObjectsFlags: u32 { + #[doc(alias = "OSTREE_REPO_LIST_OBJECTS_LOOSE")] + const LOOSE = ffi::OSTREE_REPO_LIST_OBJECTS_LOOSE as u32; + #[doc(alias = "OSTREE_REPO_LIST_OBJECTS_PACKED")] + const PACKED = ffi::OSTREE_REPO_LIST_OBJECTS_PACKED as u32; + #[doc(alias = "OSTREE_REPO_LIST_OBJECTS_ALL")] + const ALL = ffi::OSTREE_REPO_LIST_OBJECTS_ALL as u32; + #[doc(alias = "OSTREE_REPO_LIST_OBJECTS_NO_PARENTS")] + const NO_PARENTS = ffi::OSTREE_REPO_LIST_OBJECTS_NO_PARENTS as u32; + } +} + +impl fmt::Display for RepoListObjectsFlags { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + <Self as fmt::Debug>::fmt(self, f) + } +} + +#[doc(hidden)] +impl IntoGlib for RepoListObjectsFlags { + type GlibType = ffi::OstreeRepoListObjectsFlags; + + fn into_glib(self) -> ffi::OstreeRepoListObjectsFlags { + self.bits() + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeRepoListObjectsFlags> for RepoListObjectsFlags { + unsafe fn from_glib(value: ffi::OstreeRepoListObjectsFlags) -> Self { + Self::from_bits_truncate(value) + } +} + +bitflags! { + #[doc(alias = "OstreeRepoListRefsExtFlags")] + pub struct RepoListRefsExtFlags: u32 { + #[doc(alias = "OSTREE_REPO_LIST_REFS_EXT_NONE")] + const NONE = ffi::OSTREE_REPO_LIST_REFS_EXT_NONE as u32; + #[doc(alias = "OSTREE_REPO_LIST_REFS_EXT_ALIASES")] + const ALIASES = ffi::OSTREE_REPO_LIST_REFS_EXT_ALIASES as u32; + #[doc(alias = "OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_REMOTES")] + const EXCLUDE_REMOTES = ffi::OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_REMOTES as u32; + #[doc(alias = "OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_MIRRORS")] + const EXCLUDE_MIRRORS = ffi::OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_MIRRORS as u32; + } +} + +impl fmt::Display for RepoListRefsExtFlags { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + <Self as fmt::Debug>::fmt(self, f) + } +} + +#[doc(hidden)] +impl IntoGlib for RepoListRefsExtFlags { + type GlibType = ffi::OstreeRepoListRefsExtFlags; + + fn into_glib(self) -> ffi::OstreeRepoListRefsExtFlags { + self.bits() + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeRepoListRefsExtFlags> for RepoListRefsExtFlags { + unsafe fn from_glib(value: ffi::OstreeRepoListRefsExtFlags) -> Self { + Self::from_bits_truncate(value) + } +} + +bitflags! { + #[doc(alias = "OstreeRepoPruneFlags")] + pub struct RepoPruneFlags: u32 { + #[doc(alias = "OSTREE_REPO_PRUNE_FLAGS_NONE")] + const NONE = ffi::OSTREE_REPO_PRUNE_FLAGS_NONE as u32; + #[doc(alias = "OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE")] + const NO_PRUNE = ffi::OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE as u32; + #[doc(alias = "OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY")] + const REFS_ONLY = ffi::OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY as u32; + #[doc(alias = "OSTREE_REPO_PRUNE_FLAGS_COMMIT_ONLY")] + const COMMIT_ONLY = ffi::OSTREE_REPO_PRUNE_FLAGS_COMMIT_ONLY as u32; + } +} + +impl fmt::Display for RepoPruneFlags { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + <Self as fmt::Debug>::fmt(self, f) + } +} + +#[doc(hidden)] +impl IntoGlib for RepoPruneFlags { + type GlibType = ffi::OstreeRepoPruneFlags; + + fn into_glib(self) -> ffi::OstreeRepoPruneFlags { + self.bits() + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeRepoPruneFlags> for RepoPruneFlags { + unsafe fn from_glib(value: ffi::OstreeRepoPruneFlags) -> Self { + Self::from_bits_truncate(value) + } +} + +bitflags! { + #[doc(alias = "OstreeRepoPullFlags")] + pub struct RepoPullFlags: u32 { + #[doc(alias = "OSTREE_REPO_PULL_FLAGS_NONE")] + const NONE = ffi::OSTREE_REPO_PULL_FLAGS_NONE as u32; + #[doc(alias = "OSTREE_REPO_PULL_FLAGS_MIRROR")] + const MIRROR = ffi::OSTREE_REPO_PULL_FLAGS_MIRROR as u32; + #[doc(alias = "OSTREE_REPO_PULL_FLAGS_COMMIT_ONLY")] + const COMMIT_ONLY = ffi::OSTREE_REPO_PULL_FLAGS_COMMIT_ONLY as u32; + #[doc(alias = "OSTREE_REPO_PULL_FLAGS_UNTRUSTED")] + const UNTRUSTED = ffi::OSTREE_REPO_PULL_FLAGS_UNTRUSTED as u32; + #[doc(alias = "OSTREE_REPO_PULL_FLAGS_BAREUSERONLY_FILES")] + const BAREUSERONLY_FILES = ffi::OSTREE_REPO_PULL_FLAGS_BAREUSERONLY_FILES as u32; + #[doc(alias = "OSTREE_REPO_PULL_FLAGS_TRUSTED_HTTP")] + const TRUSTED_HTTP = ffi::OSTREE_REPO_PULL_FLAGS_TRUSTED_HTTP as u32; + } +} + +impl fmt::Display for RepoPullFlags { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + <Self as fmt::Debug>::fmt(self, f) + } +} + +#[doc(hidden)] +impl IntoGlib for RepoPullFlags { + type GlibType = ffi::OstreeRepoPullFlags; + + fn into_glib(self) -> ffi::OstreeRepoPullFlags { + self.bits() + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeRepoPullFlags> for RepoPullFlags { + unsafe fn from_glib(value: ffi::OstreeRepoPullFlags) -> Self { + Self::from_bits_truncate(value) + } +} + +bitflags! { + #[doc(alias = "OstreeRepoResolveRevExtFlags")] + pub struct RepoResolveRevExtFlags: u32 { + #[doc(alias = "OSTREE_REPO_RESOLVE_REV_EXT_NONE")] + const NONE = ffi::OSTREE_REPO_RESOLVE_REV_EXT_NONE as u32; + #[doc(alias = "OSTREE_REPO_RESOLVE_REV_EXT_LOCAL_ONLY")] + const LOCAL_ONLY = ffi::OSTREE_REPO_RESOLVE_REV_EXT_LOCAL_ONLY as u32; + } +} + +impl fmt::Display for RepoResolveRevExtFlags { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + <Self as fmt::Debug>::fmt(self, f) + } +} + +#[doc(hidden)] +impl IntoGlib for RepoResolveRevExtFlags { + type GlibType = ffi::OstreeRepoResolveRevExtFlags; + + fn into_glib(self) -> ffi::OstreeRepoResolveRevExtFlags { + self.bits() + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeRepoResolveRevExtFlags> for RepoResolveRevExtFlags { + unsafe fn from_glib(value: ffi::OstreeRepoResolveRevExtFlags) -> Self { + Self::from_bits_truncate(value) + } +} + +#[cfg(any(feature = "v2021_4", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_4")))] +bitflags! { + #[doc(alias = "OstreeRepoVerifyFlags")] + pub struct RepoVerifyFlags: u32 { + #[doc(alias = "OSTREE_REPO_VERIFY_FLAGS_NONE")] + const NONE = ffi::OSTREE_REPO_VERIFY_FLAGS_NONE as u32; + #[doc(alias = "OSTREE_REPO_VERIFY_FLAGS_NO_GPG")] + const NO_GPG = ffi::OSTREE_REPO_VERIFY_FLAGS_NO_GPG as u32; + #[doc(alias = "OSTREE_REPO_VERIFY_FLAGS_NO_SIGNAPI")] + const NO_SIGNAPI = ffi::OSTREE_REPO_VERIFY_FLAGS_NO_SIGNAPI as u32; + } +} + +#[cfg(any(feature = "v2021_4", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_4")))] +impl fmt::Display for RepoVerifyFlags { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + <Self as fmt::Debug>::fmt(self, f) + } +} + +#[cfg(any(feature = "v2021_4", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_4")))] +#[doc(hidden)] +impl IntoGlib for RepoVerifyFlags { + type GlibType = ffi::OstreeRepoVerifyFlags; + + fn into_glib(self) -> ffi::OstreeRepoVerifyFlags { + self.bits() + } +} + +#[cfg(any(feature = "v2021_4", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_4")))] +#[doc(hidden)] +impl FromGlib<ffi::OstreeRepoVerifyFlags> for RepoVerifyFlags { + unsafe fn from_glib(value: ffi::OstreeRepoVerifyFlags) -> Self { + Self::from_bits_truncate(value) + } +} + +bitflags! { + #[doc(alias = "OstreeSePolicyRestoreconFlags")] + pub struct SePolicyRestoreconFlags: u32 { + #[doc(alias = "OSTREE_SEPOLICY_RESTORECON_FLAGS_NONE")] + const NONE = ffi::OSTREE_SEPOLICY_RESTORECON_FLAGS_NONE as u32; + #[doc(alias = "OSTREE_SEPOLICY_RESTORECON_FLAGS_ALLOW_NOLABEL")] + const ALLOW_NOLABEL = ffi::OSTREE_SEPOLICY_RESTORECON_FLAGS_ALLOW_NOLABEL as u32; + #[doc(alias = "OSTREE_SEPOLICY_RESTORECON_FLAGS_KEEP_EXISTING")] + const KEEP_EXISTING = ffi::OSTREE_SEPOLICY_RESTORECON_FLAGS_KEEP_EXISTING as u32; + } +} + +impl fmt::Display for SePolicyRestoreconFlags { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + <Self as fmt::Debug>::fmt(self, f) + } +} + +#[doc(hidden)] +impl IntoGlib for SePolicyRestoreconFlags { + type GlibType = ffi::OstreeSePolicyRestoreconFlags; + + fn into_glib(self) -> ffi::OstreeSePolicyRestoreconFlags { + self.bits() + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeSePolicyRestoreconFlags> for SePolicyRestoreconFlags { + unsafe fn from_glib(value: ffi::OstreeSePolicyRestoreconFlags) -> Self { + Self::from_bits_truncate(value) + } +} + +bitflags! { + #[doc(alias = "OstreeSysrootSimpleWriteDeploymentFlags")] + pub struct SysrootSimpleWriteDeploymentFlags: u32 { + #[doc(alias = "OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NONE")] + const NONE = ffi::OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NONE as u32; + #[doc(alias = "OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN")] + const RETAIN = ffi::OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN as u32; + #[doc(alias = "OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NOT_DEFAULT")] + const NOT_DEFAULT = ffi::OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NOT_DEFAULT as u32; + #[doc(alias = "OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NO_CLEAN")] + const NO_CLEAN = ffi::OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NO_CLEAN as u32; + #[doc(alias = "OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_PENDING")] + const RETAIN_PENDING = ffi::OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_PENDING as u32; + #[doc(alias = "OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_ROLLBACK")] + const RETAIN_ROLLBACK = ffi::OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_ROLLBACK as u32; + } +} + +impl fmt::Display for SysrootSimpleWriteDeploymentFlags { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + <Self as fmt::Debug>::fmt(self, f) + } +} + +#[doc(hidden)] +impl IntoGlib for SysrootSimpleWriteDeploymentFlags { + type GlibType = ffi::OstreeSysrootSimpleWriteDeploymentFlags; + + fn into_glib(self) -> ffi::OstreeSysrootSimpleWriteDeploymentFlags { + self.bits() + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeSysrootSimpleWriteDeploymentFlags> for SysrootSimpleWriteDeploymentFlags { + unsafe fn from_glib(value: ffi::OstreeSysrootSimpleWriteDeploymentFlags) -> Self { + Self::from_bits_truncate(value) + } +} + +bitflags! { + #[doc(alias = "OstreeSysrootUpgraderFlags")] + pub struct SysrootUpgraderFlags: u32 { + #[doc(alias = "OSTREE_SYSROOT_UPGRADER_FLAGS_IGNORE_UNCONFIGURED")] + const IGNORE_UNCONFIGURED = ffi::OSTREE_SYSROOT_UPGRADER_FLAGS_IGNORE_UNCONFIGURED as u32; + #[doc(alias = "OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE")] + const STAGE = ffi::OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE as u32; + } +} + +impl fmt::Display for SysrootUpgraderFlags { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + <Self as fmt::Debug>::fmt(self, f) + } +} + +#[doc(hidden)] +impl IntoGlib for SysrootUpgraderFlags { + type GlibType = ffi::OstreeSysrootUpgraderFlags; + + fn into_glib(self) -> ffi::OstreeSysrootUpgraderFlags { + self.bits() + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeSysrootUpgraderFlags> for SysrootUpgraderFlags { + unsafe fn from_glib(value: ffi::OstreeSysrootUpgraderFlags) -> Self { + Self::from_bits_truncate(value) + } +} + +impl StaticType for SysrootUpgraderFlags { + fn static_type() -> Type { + unsafe { from_glib(ffi::ostree_sysroot_upgrader_flags_get_type()) } + } +} + +impl glib::value::ValueType for SysrootUpgraderFlags { + type Type = Self; +} + +unsafe impl<'a> FromValue<'a> for SysrootUpgraderFlags { + type Checker = glib::value::GenericValueTypeChecker<Self>; + + unsafe fn from_value(value: &'a glib::Value) -> Self { + from_glib(glib::gobject_ffi::g_value_get_flags(value.to_glib_none().0)) + } +} + +impl ToValue for SysrootUpgraderFlags { + fn to_value(&self) -> glib::Value { + let mut value = glib::Value::for_value_type::<Self>(); + unsafe { + glib::gobject_ffi::g_value_set_flags(value.to_glib_none_mut().0, self.into_glib()); + } + value + } + + fn value_type(&self) -> glib::Type { + Self::static_type() + } +} + +bitflags! { + #[doc(alias = "OstreeSysrootUpgraderPullFlags")] + pub struct SysrootUpgraderPullFlags: u32 { + #[doc(alias = "OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_NONE")] + const NONE = ffi::OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_NONE as u32; + #[doc(alias = "OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_ALLOW_OLDER")] + const ALLOW_OLDER = ffi::OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_ALLOW_OLDER as u32; + #[doc(alias = "OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_SYNTHETIC")] + const SYNTHETIC = ffi::OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_SYNTHETIC as u32; + } +} + +impl fmt::Display for SysrootUpgraderPullFlags { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + <Self as fmt::Debug>::fmt(self, f) + } +} + +#[doc(hidden)] +impl IntoGlib for SysrootUpgraderPullFlags { + type GlibType = ffi::OstreeSysrootUpgraderPullFlags; + + fn into_glib(self) -> ffi::OstreeSysrootUpgraderPullFlags { + self.bits() + } +} + +#[doc(hidden)] +impl FromGlib<ffi::OstreeSysrootUpgraderPullFlags> for SysrootUpgraderPullFlags { + unsafe fn from_glib(value: ffi::OstreeSysrootUpgraderPullFlags) -> Self { + Self::from_bits_truncate(value) + } +} + diff --git a/rust-bindings/src/auto/functions.rs b/rust-bindings/src/auto/functions.rs new file mode 100644 index 0000000000..cf0aa2ce6a --- /dev/null +++ b/rust-bindings/src/auto/functions.rs @@ -0,0 +1,385 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +#[cfg(any(feature = "v2020_1", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_1")))] +use crate::CommitSizesEntry; +use crate::DiffFlags; +use crate::DiffItem; +use crate::ObjectType; +use glib::object::IsA; +use glib::translate::*; +use std::mem; +use std::ptr; + + +#[cfg(any(feature = "v2017_15", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_15")))] +#[doc(alias = "ostree_break_hardlink")] +pub fn break_hardlink<P: IsA<gio::Cancellable>>(dfd: i32, path: &str, skip_xattrs: bool, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_break_hardlink(dfd, path.to_glib_none().0, skip_xattrs.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } +} + +#[cfg(any(feature = "v2017_4", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_4")))] +#[doc(alias = "ostree_check_version")] +pub fn check_version(required_year: u32, required_release: u32) -> bool { + unsafe { + from_glib(ffi::ostree_check_version(required_year, required_release)) + } +} + +//#[doc(alias = "ostree_checksum_bytes_peek")] +//pub fn checksum_bytes_peek(bytes: &glib::Variant) -> /*Unimplemented*/FixedArray TypeId { ns_id: 0, id: 3 }; 32 { +// unsafe { TODO: call ffi:ostree_checksum_bytes_peek() } +//} + +//#[doc(alias = "ostree_checksum_bytes_peek_validate")] +//pub fn checksum_bytes_peek_validate(bytes: &glib::Variant) -> Result</*Unimplemented*/FixedArray TypeId { ns_id: 0, id: 3 }; 32, glib::Error> { +// unsafe { TODO: call ffi:ostree_checksum_bytes_peek_validate() } +//} + +#[doc(alias = "ostree_checksum_from_bytes_v")] +pub fn checksum_from_bytes_v(csum_v: &glib::Variant) -> Option<glib::GString> { + unsafe { + from_glib_full(ffi::ostree_checksum_from_bytes_v(csum_v.to_glib_none().0)) + } +} + +#[doc(alias = "ostree_checksum_to_bytes_v")] +pub fn checksum_to_bytes_v(checksum: &str) -> Option<glib::Variant> { + unsafe { + from_glib_full(ffi::ostree_checksum_to_bytes_v(checksum.to_glib_none().0)) + } +} + +#[cfg(any(feature = "v2018_2", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_2")))] +#[doc(alias = "ostree_commit_get_content_checksum")] +pub fn commit_get_content_checksum(commit_variant: &glib::Variant) -> Option<glib::GString> { + unsafe { + from_glib_full(ffi::ostree_commit_get_content_checksum(commit_variant.to_glib_none().0)) + } +} + +#[cfg(any(feature = "v2020_1", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_1")))] +#[doc(alias = "ostree_commit_get_object_sizes")] +pub fn commit_get_object_sizes(commit_variant: &glib::Variant) -> Result<Vec<CommitSizesEntry>, glib::Error> { + unsafe { + let mut out_sizes_entries = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_commit_get_object_sizes(commit_variant.to_glib_none().0, &mut out_sizes_entries, &mut error); + if error.is_null() { Ok(FromGlibPtrContainer::from_glib_container(out_sizes_entries)) } else { Err(from_glib_full(error)) } + } +} + +#[doc(alias = "ostree_commit_get_parent")] +pub fn commit_get_parent(commit_variant: &glib::Variant) -> Option<glib::GString> { + unsafe { + from_glib_full(ffi::ostree_commit_get_parent(commit_variant.to_glib_none().0)) + } +} + +#[cfg(any(feature = "v2016_3", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_3")))] +#[doc(alias = "ostree_commit_get_timestamp")] +pub fn commit_get_timestamp(commit_variant: &glib::Variant) -> u64 { + unsafe { + ffi::ostree_commit_get_timestamp(commit_variant.to_glib_none().0) + } +} + +//#[cfg(any(feature = "v2021_1", feature = "dox"))] +//#[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_1")))] +//#[doc(alias = "ostree_commit_metadata_for_bootable")] +//pub fn commit_metadata_for_bootable<P: IsA<gio::File>, Q: IsA<gio::Cancellable>>(root: &P, dict: /*Ignored*/&glib::VariantDict, cancellable: Option<&Q>) -> Result<(), glib::Error> { +// unsafe { TODO: call ffi:ostree_commit_metadata_for_bootable() } +//} + +#[doc(alias = "ostree_content_file_parse")] +pub fn content_file_parse<P: IsA<gio::File>, Q: IsA<gio::Cancellable>>(compressed: bool, content_path: &P, trusted: bool, cancellable: Option<&Q>) -> Result<(gio::InputStream, gio::FileInfo, glib::Variant), glib::Error> { + unsafe { + let mut out_input = ptr::null_mut(); + let mut out_file_info = ptr::null_mut(); + let mut out_xattrs = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_content_file_parse(compressed.into_glib(), content_path.as_ref().to_glib_none().0, trusted.into_glib(), &mut out_input, &mut out_file_info, &mut out_xattrs, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok((from_glib_full(out_input), from_glib_full(out_file_info), from_glib_full(out_xattrs))) } else { Err(from_glib_full(error)) } + } +} + +#[doc(alias = "ostree_content_file_parse_at")] +pub fn content_file_parse_at<P: IsA<gio::Cancellable>>(compressed: bool, parent_dfd: i32, path: &str, trusted: bool, cancellable: Option<&P>) -> Result<(gio::InputStream, gio::FileInfo, glib::Variant), glib::Error> { + unsafe { + let mut out_input = ptr::null_mut(); + let mut out_file_info = ptr::null_mut(); + let mut out_xattrs = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_content_file_parse_at(compressed.into_glib(), parent_dfd, path.to_glib_none().0, trusted.into_glib(), &mut out_input, &mut out_file_info, &mut out_xattrs, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok((from_glib_full(out_input), from_glib_full(out_file_info), from_glib_full(out_xattrs))) } else { Err(from_glib_full(error)) } + } +} + +#[doc(alias = "ostree_content_stream_parse")] +pub fn content_stream_parse<P: IsA<gio::InputStream>, Q: IsA<gio::Cancellable>>(compressed: bool, input: &P, input_length: u64, trusted: bool, cancellable: Option<&Q>) -> Result<(gio::InputStream, gio::FileInfo, glib::Variant), glib::Error> { + unsafe { + let mut out_input = ptr::null_mut(); + let mut out_file_info = ptr::null_mut(); + let mut out_xattrs = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_content_stream_parse(compressed.into_glib(), input.as_ref().to_glib_none().0, input_length, trusted.into_glib(), &mut out_input, &mut out_file_info, &mut out_xattrs, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok((from_glib_full(out_input), from_glib_full(out_file_info), from_glib_full(out_xattrs))) } else { Err(from_glib_full(error)) } + } +} + +#[doc(alias = "ostree_create_directory_metadata")] +pub fn create_directory_metadata(dir_info: &gio::FileInfo, xattrs: Option<&glib::Variant>) -> Option<glib::Variant> { + unsafe { + from_glib_full(ffi::ostree_create_directory_metadata(dir_info.to_glib_none().0, xattrs.to_glib_none().0)) + } +} + +#[doc(alias = "ostree_diff_dirs")] +pub fn diff_dirs<P: IsA<gio::File>, Q: IsA<gio::File>, R: IsA<gio::Cancellable>>(flags: DiffFlags, a: &P, b: &Q, modified: &[&DiffItem], removed: &[gio::File], added: &[gio::File], cancellable: Option<&R>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_diff_dirs(flags.into_glib(), a.as_ref().to_glib_none().0, b.as_ref().to_glib_none().0, modified.to_glib_none().0, removed.to_glib_none().0, added.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } +} + +//#[cfg(any(feature = "v2017_4", feature = "dox"))] +//#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_4")))] +//#[doc(alias = "ostree_diff_dirs_with_options")] +//pub fn diff_dirs_with_options<P: IsA<gio::File>, Q: IsA<gio::File>, R: IsA<gio::Cancellable>>(flags: DiffFlags, a: &P, b: &Q, modified: &[&DiffItem], removed: &[gio::File], added: &[gio::File], options: /*Ignored*/Option<&mut DiffDirsOptions>, cancellable: Option<&R>) -> Result<(), glib::Error> { +// unsafe { TODO: call ffi:ostree_diff_dirs_with_options() } +//} + +#[doc(alias = "ostree_diff_print")] +pub fn diff_print<P: IsA<gio::File>, Q: IsA<gio::File>>(a: &P, b: &Q, modified: &[&DiffItem], removed: &[gio::File], added: &[gio::File]) { + unsafe { + ffi::ostree_diff_print(a.as_ref().to_glib_none().0, b.as_ref().to_glib_none().0, modified.to_glib_none().0, removed.to_glib_none().0, added.to_glib_none().0); + } +} + +#[cfg(any(feature = "v2017_10", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_10")))] +#[doc(alias = "ostree_gpg_error_quark")] +pub fn gpg_error_quark() -> glib::Quark { + unsafe { + from_glib(ffi::ostree_gpg_error_quark()) + } +} + +#[doc(alias = "ostree_metadata_variant_type")] +pub fn metadata_variant_type(objtype: ObjectType) -> Option<glib::VariantType> { + unsafe { + from_glib_none(ffi::ostree_metadata_variant_type(objtype.into_glib())) + } +} + +#[doc(alias = "ostree_object_from_string")] +pub fn object_from_string(str: &str) -> (glib::GString, ObjectType) { + unsafe { + let mut out_checksum = ptr::null_mut(); + let mut out_objtype = mem::MaybeUninit::uninit(); + ffi::ostree_object_from_string(str.to_glib_none().0, &mut out_checksum, out_objtype.as_mut_ptr()); + let out_objtype = out_objtype.assume_init(); + (from_glib_full(out_checksum), from_glib(out_objtype)) + } +} + +#[doc(alias = "ostree_object_name_deserialize")] +pub fn object_name_deserialize(variant: &glib::Variant) -> (glib::GString, ObjectType) { + unsafe { + let mut out_checksum = ptr::null(); + let mut out_objtype = mem::MaybeUninit::uninit(); + ffi::ostree_object_name_deserialize(variant.to_glib_none().0, &mut out_checksum, out_objtype.as_mut_ptr()); + let out_objtype = out_objtype.assume_init(); + (from_glib_none(out_checksum), from_glib(out_objtype)) + } +} + +#[doc(alias = "ostree_object_name_serialize")] +pub fn object_name_serialize(checksum: &str, objtype: ObjectType) -> Option<glib::Variant> { + unsafe { + from_glib_none(ffi::ostree_object_name_serialize(checksum.to_glib_none().0, objtype.into_glib())) + } +} + +#[doc(alias = "ostree_object_to_string")] +pub fn object_to_string(checksum: &str, objtype: ObjectType) -> Option<glib::GString> { + unsafe { + from_glib_full(ffi::ostree_object_to_string(checksum.to_glib_none().0, objtype.into_glib())) + } +} + +#[doc(alias = "ostree_object_type_from_string")] +pub fn object_type_from_string(str: &str) -> ObjectType { + unsafe { + from_glib(ffi::ostree_object_type_from_string(str.to_glib_none().0)) + } +} + +#[doc(alias = "ostree_object_type_to_string")] +pub fn object_type_to_string(objtype: ObjectType) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_object_type_to_string(objtype.into_glib())) + } +} + +#[doc(alias = "ostree_parse_refspec")] +pub fn parse_refspec(refspec: &str) -> Result<(Option<glib::GString>, glib::GString), glib::Error> { + unsafe { + let mut out_remote = ptr::null_mut(); + let mut out_ref = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_parse_refspec(refspec.to_glib_none().0, &mut out_remote, &mut out_ref, &mut error); + if error.is_null() { Ok((from_glib_full(out_remote), from_glib_full(out_ref))) } else { Err(from_glib_full(error)) } + } +} + +#[cfg(any(feature = "v2016_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_6")))] +#[doc(alias = "ostree_raw_file_to_archive_z2_stream")] +pub fn raw_file_to_archive_z2_stream<P: IsA<gio::InputStream>, Q: IsA<gio::Cancellable>>(input: &P, file_info: &gio::FileInfo, xattrs: Option<&glib::Variant>, cancellable: Option<&Q>) -> Result<gio::InputStream, glib::Error> { + unsafe { + let mut out_input = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_raw_file_to_archive_z2_stream(input.as_ref().to_glib_none().0, file_info.to_glib_none().0, xattrs.to_glib_none().0, &mut out_input, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_input)) } else { Err(from_glib_full(error)) } + } +} + +#[cfg(any(feature = "v2017_3", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_3")))] +#[doc(alias = "ostree_raw_file_to_archive_z2_stream_with_options")] +pub fn raw_file_to_archive_z2_stream_with_options<P: IsA<gio::InputStream>, Q: IsA<gio::Cancellable>>(input: &P, file_info: &gio::FileInfo, xattrs: Option<&glib::Variant>, options: Option<&glib::Variant>, cancellable: Option<&Q>) -> Result<gio::InputStream, glib::Error> { + unsafe { + let mut out_input = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_raw_file_to_archive_z2_stream_with_options(input.as_ref().to_glib_none().0, file_info.to_glib_none().0, xattrs.to_glib_none().0, options.to_glib_none().0, &mut out_input, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_input)) } else { Err(from_glib_full(error)) } + } +} + +#[doc(alias = "ostree_raw_file_to_content_stream")] +pub fn raw_file_to_content_stream<P: IsA<gio::InputStream>, Q: IsA<gio::Cancellable>>(input: &P, file_info: &gio::FileInfo, xattrs: Option<&glib::Variant>, cancellable: Option<&Q>) -> Result<(gio::InputStream, u64), glib::Error> { + unsafe { + let mut out_input = ptr::null_mut(); + let mut out_length = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_raw_file_to_content_stream(input.as_ref().to_glib_none().0, file_info.to_glib_none().0, xattrs.to_glib_none().0, &mut out_input, out_length.as_mut_ptr(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + let out_length = out_length.assume_init(); + if error.is_null() { Ok((from_glib_full(out_input), out_length)) } else { Err(from_glib_full(error)) } + } +} + +#[doc(alias = "ostree_validate_checksum_string")] +pub fn validate_checksum_string(sha256: &str) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_validate_checksum_string(sha256.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } +} + +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +#[doc(alias = "ostree_validate_collection_id")] +pub fn validate_collection_id(collection_id: Option<&str>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_validate_collection_id(collection_id.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } +} + +#[cfg(any(feature = "v2017_8", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_8")))] +#[doc(alias = "ostree_validate_remote_name")] +pub fn validate_remote_name(remote_name: &str) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_validate_remote_name(remote_name.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } +} + +#[doc(alias = "ostree_validate_rev")] +pub fn validate_rev(rev: &str) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_validate_rev(rev.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } +} + +#[doc(alias = "ostree_validate_structureof_checksum_string")] +pub fn validate_structureof_checksum_string(checksum: &str) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_validate_structureof_checksum_string(checksum.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } +} + +#[doc(alias = "ostree_validate_structureof_commit")] +pub fn validate_structureof_commit(commit: &glib::Variant) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_validate_structureof_commit(commit.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } +} + +#[doc(alias = "ostree_validate_structureof_csum_v")] +pub fn validate_structureof_csum_v(checksum: &glib::Variant) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_validate_structureof_csum_v(checksum.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } +} + +#[doc(alias = "ostree_validate_structureof_dirmeta")] +pub fn validate_structureof_dirmeta(dirmeta: &glib::Variant) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_validate_structureof_dirmeta(dirmeta.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } +} + +#[doc(alias = "ostree_validate_structureof_dirtree")] +pub fn validate_structureof_dirtree(dirtree: &glib::Variant) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_validate_structureof_dirtree(dirtree.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } +} + +#[doc(alias = "ostree_validate_structureof_file_mode")] +pub fn validate_structureof_file_mode(mode: u32) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_validate_structureof_file_mode(mode, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } +} + +#[doc(alias = "ostree_validate_structureof_objtype")] +pub fn validate_structureof_objtype(objtype: u8) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_validate_structureof_objtype(objtype, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } +} diff --git a/rust-bindings/src/auto/gpg_verify_result.rs b/rust-bindings/src/auto/gpg_verify_result.rs new file mode 100644 index 0000000000..121f8f7ca2 --- /dev/null +++ b/rust-bindings/src/auto/gpg_verify_result.rs @@ -0,0 +1,90 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use crate::GpgSignatureFormatFlags; +use glib::translate::*; +use std::fmt; +use std::mem; +#[cfg(any(feature = "v2016_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_6")))] +use std::ptr; + +glib::wrapper! { + #[doc(alias = "OstreeGpgVerifyResult")] + pub struct GpgVerifyResult(Object<ffi::OstreeGpgVerifyResult>); + + match fn { + type_ => || ffi::ostree_gpg_verify_result_get_type(), + } +} + +impl GpgVerifyResult { + #[doc(alias = "ostree_gpg_verify_result_count_all")] + pub fn count_all(&self) -> u32 { + unsafe { + ffi::ostree_gpg_verify_result_count_all(self.to_glib_none().0) + } + } + + #[doc(alias = "ostree_gpg_verify_result_count_valid")] + pub fn count_valid(&self) -> u32 { + unsafe { + ffi::ostree_gpg_verify_result_count_valid(self.to_glib_none().0) + } + } + + #[doc(alias = "ostree_gpg_verify_result_describe")] + pub fn describe(&self, signature_index: u32, output_buffer: &mut glib::String, line_prefix: Option<&str>, flags: GpgSignatureFormatFlags) { + unsafe { + ffi::ostree_gpg_verify_result_describe(self.to_glib_none().0, signature_index, output_buffer.to_glib_none_mut().0, line_prefix.to_glib_none().0, flags.into_glib()); + } + } + + //#[doc(alias = "ostree_gpg_verify_result_get")] + //pub fn get(&self, signature_index: u32, attrs: /*Unimplemented*/&CArray TypeId { ns_id: 1, id: 31 }) -> Option<glib::Variant> { + // unsafe { TODO: call ffi:ostree_gpg_verify_result_get() } + //} + + #[doc(alias = "ostree_gpg_verify_result_get_all")] + #[doc(alias = "get_all")] + pub fn all(&self, signature_index: u32) -> Option<glib::Variant> { + unsafe { + from_glib_none(ffi::ostree_gpg_verify_result_get_all(self.to_glib_none().0, signature_index)) + } + } + + #[doc(alias = "ostree_gpg_verify_result_lookup")] + pub fn lookup(&self, key_id: &str) -> Option<u32> { + unsafe { + let mut out_signature_index = mem::MaybeUninit::uninit(); + let ret = from_glib(ffi::ostree_gpg_verify_result_lookup(self.to_glib_none().0, key_id.to_glib_none().0, out_signature_index.as_mut_ptr())); + let out_signature_index = out_signature_index.assume_init(); + if ret { Some(out_signature_index) } else { None } + } + } + + #[cfg(any(feature = "v2016_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_6")))] + #[doc(alias = "ostree_gpg_verify_result_require_valid_signature")] + pub fn require_valid_signature(&self) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_gpg_verify_result_require_valid_signature(self.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_gpg_verify_result_describe_variant")] + pub fn describe_variant(variant: &glib::Variant, output_buffer: &mut glib::String, line_prefix: Option<&str>, flags: GpgSignatureFormatFlags) { + unsafe { + ffi::ostree_gpg_verify_result_describe_variant(variant.to_glib_none().0, output_buffer.to_glib_none_mut().0, line_prefix.to_glib_none().0, flags.into_glib()); + } + } +} + +impl fmt::Display for GpgVerifyResult { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("GpgVerifyResult") + } +} diff --git a/rust-bindings/src/auto/mod.rs b/rust-bindings/src/auto/mod.rs new file mode 100644 index 0000000000..c66182147e --- /dev/null +++ b/rust-bindings/src/auto/mod.rs @@ -0,0 +1,217 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +mod async_progress; +pub use self::async_progress::{AsyncProgress}; + +mod bootconfig_parser; +pub use self::bootconfig_parser::{BootconfigParser}; + +mod content_writer; +pub use self::content_writer::{ContentWriter}; + +mod deployment; +pub use self::deployment::{Deployment}; + +mod gpg_verify_result; +pub use self::gpg_verify_result::{GpgVerifyResult}; + +mod mutable_tree; +pub use self::mutable_tree::{MutableTree}; + +mod repo; +pub use self::repo::{Repo}; + +mod repo_file; +pub use self::repo_file::{RepoFile}; + +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +mod repo_finder; +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +pub use self::repo_finder::{RepoFinder, NONE_REPO_FINDER}; + +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +mod repo_finder_avahi; +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +pub use self::repo_finder_avahi::{RepoFinderAvahi}; + +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +mod repo_finder_config; +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +pub use self::repo_finder_config::{RepoFinderConfig}; + +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +mod repo_finder_mount; +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +pub use self::repo_finder_mount::{RepoFinderMount}; + +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +mod repo_finder_override; +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +pub use self::repo_finder_override::{RepoFinderOverride}; + +mod se_policy; +pub use self::se_policy::{SePolicy}; + +#[cfg(any(feature = "v2020_2", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] +mod sign; +#[cfg(any(feature = "v2020_2", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] +pub use self::sign::{Sign, NONE_SIGN}; + +mod sysroot; +pub use self::sysroot::{Sysroot}; + +mod sysroot_upgrader; +pub use self::sysroot_upgrader::{SysrootUpgrader}; + +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +mod collection_ref; +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +pub use self::collection_ref::CollectionRef; + +#[cfg(any(feature = "v2020_1", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_1")))] +mod commit_sizes_entry; +#[cfg(any(feature = "v2020_1", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_1")))] +pub use self::commit_sizes_entry::CommitSizesEntry; + +mod diff_item; +pub use self::diff_item::DiffItem; + +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +mod remote; +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +pub use self::remote::Remote; + +mod repo_commit_modifier; +pub use self::repo_commit_modifier::RepoCommitModifier; + +mod repo_dev_ino_cache; +pub use self::repo_dev_ino_cache::RepoDevInoCache; + +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +mod repo_finder_result; +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +pub use self::repo_finder_result::RepoFinderResult; + +mod enums; +pub use self::enums::DeploymentUnlockedState; +pub use self::enums::GpgSignatureAttr; +pub use self::enums::ObjectType; +#[cfg(any(feature = "v2018_2", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_2")))] +pub use self::enums::RepoCheckoutFilterResult; +pub use self::enums::RepoCheckoutMode; +pub use self::enums::RepoCheckoutOverwriteMode; +pub use self::enums::RepoCommitFilterResult; +pub use self::enums::RepoCommitIterResult; +pub use self::enums::RepoMode; +pub use self::enums::RepoRemoteChange; +pub use self::enums::StaticDeltaGenerateOpt; + +mod flags; +#[cfg(any(feature = "v2017_13", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_13")))] +pub use self::flags::ChecksumFlags; +pub use self::flags::DiffFlags; +pub use self::flags::GpgSignatureFormatFlags; +pub use self::flags::RepoCommitModifierFlags; +#[cfg(any(feature = "v2015_7", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2015_7")))] +pub use self::flags::RepoCommitState; +pub use self::flags::RepoCommitTraverseFlags; +pub use self::flags::RepoListObjectsFlags; +pub use self::flags::RepoListRefsExtFlags; +pub use self::flags::RepoPruneFlags; +pub use self::flags::RepoPullFlags; +pub use self::flags::RepoResolveRevExtFlags; +#[cfg(any(feature = "v2021_4", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_4")))] +pub use self::flags::RepoVerifyFlags; +pub use self::flags::SePolicyRestoreconFlags; +pub use self::flags::SysrootSimpleWriteDeploymentFlags; +pub use self::flags::SysrootUpgraderFlags; +pub use self::flags::SysrootUpgraderPullFlags; + +pub mod functions; + +mod constants; +pub use self::constants::COMMIT_GVARIANT_STRING; +#[cfg(any(feature = "v2020_4", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_4")))] +pub use self::constants::COMMIT_META_KEY_ARCHITECTURE; +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +pub use self::constants::COMMIT_META_KEY_COLLECTION_BINDING; +#[cfg(any(feature = "v2017_7", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_7")))] +pub use self::constants::COMMIT_META_KEY_ENDOFLIFE; +#[cfg(any(feature = "v2017_7", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_7")))] +pub use self::constants::COMMIT_META_KEY_ENDOFLIFE_REBASE; +#[cfg(any(feature = "v2017_9", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_9")))] +pub use self::constants::COMMIT_META_KEY_REF_BINDING; +#[cfg(any(feature = "v2017_13", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_13")))] +pub use self::constants::COMMIT_META_KEY_SOURCE_TITLE; +#[cfg(any(feature = "v2014_9", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2014_9")))] +pub use self::constants::COMMIT_META_KEY_VERSION; +pub use self::constants::DIRMETA_GVARIANT_STRING; +pub use self::constants::FILEMETA_GVARIANT_STRING; +pub use self::constants::GPG_KEY_GVARIANT_STRING; +#[cfg(any(feature = "v2021_1", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_1")))] +pub use self::constants::METADATA_KEY_BOOTABLE; +#[cfg(any(feature = "v2021_1", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_1")))] +pub use self::constants::METADATA_KEY_LINUX; +#[cfg(any(feature = "v2018_9", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_9")))] +pub use self::constants::META_KEY_DEPLOY_COLLECTION_ID; +#[cfg(any(feature = "v2018_3", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_3")))] +pub use self::constants::ORIGIN_TRANSIENT_GROUP; +#[cfg(any(feature = "v2022_2", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2022_2")))] +pub use self::constants::PATH_BOOTED; +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +pub use self::constants::REPO_METADATA_REF; +#[cfg(any(feature = "v2020_4", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_4")))] +pub use self::constants::SIGN_NAME_ED25519; +pub use self::constants::SUMMARY_GVARIANT_STRING; +pub use self::constants::SUMMARY_SIG_GVARIANT_STRING; +pub use self::constants::TREE_GVARIANT_STRING; + +#[doc(hidden)] +pub mod traits { + #[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub use super::repo_finder::RepoFinderExt; + #[cfg(any(feature = "v2020_2", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] + pub use super::sign::SignExt; +} diff --git a/rust-bindings/src/auto/mutable_tree.rs b/rust-bindings/src/auto/mutable_tree.rs new file mode 100644 index 0000000000..10b42badcf --- /dev/null +++ b/rust-bindings/src/auto/mutable_tree.rs @@ -0,0 +1,185 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +#[cfg(any(feature = "v2018_7", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_7")))] +use crate::Repo; +use glib::translate::*; +use std::fmt; +use std::ptr; + +glib::wrapper! { + #[doc(alias = "OstreeMutableTree")] + pub struct MutableTree(Object<ffi::OstreeMutableTree, ffi::OstreeMutableTreeClass>); + + match fn { + type_ => || ffi::ostree_mutable_tree_get_type(), + } +} + +impl MutableTree { + #[doc(alias = "ostree_mutable_tree_new")] + pub fn new() -> MutableTree { + unsafe { + from_glib_full(ffi::ostree_mutable_tree_new()) + } + } + + #[cfg(any(feature = "v2018_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_7")))] + #[doc(alias = "ostree_mutable_tree_new_from_checksum")] + #[doc(alias = "new_from_checksum")] + pub fn from_checksum(repo: &Repo, contents_checksum: &str, metadata_checksum: &str) -> MutableTree { + unsafe { + from_glib_full(ffi::ostree_mutable_tree_new_from_checksum(repo.to_glib_none().0, contents_checksum.to_glib_none().0, metadata_checksum.to_glib_none().0)) + } + } + + #[cfg(any(feature = "v2021_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_5")))] + #[doc(alias = "ostree_mutable_tree_new_from_commit")] + #[doc(alias = "new_from_commit")] + pub fn from_commit(repo: &Repo, rev: &str) -> Result<MutableTree, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_mutable_tree_new_from_commit(repo.to_glib_none().0, rev.to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2018_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_7")))] + #[doc(alias = "ostree_mutable_tree_check_error")] + pub fn check_error(&self) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_mutable_tree_check_error(self.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_mutable_tree_ensure_dir")] + pub fn ensure_dir(&self, name: &str) -> Result<MutableTree, glib::Error> { + unsafe { + let mut out_subdir = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_mutable_tree_ensure_dir(self.to_glib_none().0, name.to_glib_none().0, &mut out_subdir, &mut error); + if error.is_null() { Ok(from_glib_full(out_subdir)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_mutable_tree_ensure_parent_dirs")] + pub fn ensure_parent_dirs(&self, split_path: &[&str], metadata_checksum: &str) -> Result<MutableTree, glib::Error> { + unsafe { + let mut out_parent = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_mutable_tree_ensure_parent_dirs(self.to_glib_none().0, split_path.to_glib_none().0, metadata_checksum.to_glib_none().0, &mut out_parent, &mut error); + if error.is_null() { Ok(from_glib_full(out_parent)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2018_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_7")))] + #[doc(alias = "ostree_mutable_tree_fill_empty_from_dirtree")] + pub fn fill_empty_from_dirtree(&self, repo: &Repo, contents_checksum: &str, metadata_checksum: &str) -> bool { + unsafe { + from_glib(ffi::ostree_mutable_tree_fill_empty_from_dirtree(self.to_glib_none().0, repo.to_glib_none().0, contents_checksum.to_glib_none().0, metadata_checksum.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_mutable_tree_get_contents_checksum")] + #[doc(alias = "get_contents_checksum")] + pub fn contents_checksum(&self) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_mutable_tree_get_contents_checksum(self.to_glib_none().0)) + } + } + + //#[doc(alias = "ostree_mutable_tree_get_files")] + //#[doc(alias = "get_files")] + //pub fn files(&self) -> /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 } { + // unsafe { TODO: call ffi:ostree_mutable_tree_get_files() } + //} + + #[doc(alias = "ostree_mutable_tree_get_metadata_checksum")] + #[doc(alias = "get_metadata_checksum")] + pub fn metadata_checksum(&self) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_mutable_tree_get_metadata_checksum(self.to_glib_none().0)) + } + } + + //#[doc(alias = "ostree_mutable_tree_get_subdirs")] + //#[doc(alias = "get_subdirs")] + //pub fn subdirs(&self) -> /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 1, id: 44 } { + // unsafe { TODO: call ffi:ostree_mutable_tree_get_subdirs() } + //} + + #[doc(alias = "ostree_mutable_tree_lookup")] + pub fn lookup(&self, name: &str) -> Result<(glib::GString, MutableTree), glib::Error> { + unsafe { + let mut out_file_checksum = ptr::null_mut(); + let mut out_subdir = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_mutable_tree_lookup(self.to_glib_none().0, name.to_glib_none().0, &mut out_file_checksum, &mut out_subdir, &mut error); + if error.is_null() { Ok((from_glib_full(out_file_checksum), from_glib_full(out_subdir))) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2018_9", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_9")))] + #[doc(alias = "ostree_mutable_tree_remove")] + pub fn remove(&self, name: &str, allow_noent: bool) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_mutable_tree_remove(self.to_glib_none().0, name.to_glib_none().0, allow_noent.into_glib(), &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_mutable_tree_replace_file")] + pub fn replace_file(&self, name: &str, checksum: &str) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_mutable_tree_replace_file(self.to_glib_none().0, name.to_glib_none().0, checksum.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_mutable_tree_set_contents_checksum")] + pub fn set_contents_checksum(&self, checksum: &str) { + unsafe { + ffi::ostree_mutable_tree_set_contents_checksum(self.to_glib_none().0, checksum.to_glib_none().0); + } + } + + #[doc(alias = "ostree_mutable_tree_set_metadata_checksum")] + pub fn set_metadata_checksum(&self, checksum: &str) { + unsafe { + ffi::ostree_mutable_tree_set_metadata_checksum(self.to_glib_none().0, checksum.to_glib_none().0); + } + } + + #[doc(alias = "ostree_mutable_tree_walk")] + pub fn walk(&self, split_path: &[&str], start: u32) -> Result<MutableTree, glib::Error> { + unsafe { + let mut out_subdir = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_mutable_tree_walk(self.to_glib_none().0, split_path.to_glib_none().0, start, &mut out_subdir, &mut error); + if error.is_null() { Ok(from_glib_full(out_subdir)) } else { Err(from_glib_full(error)) } + } + } +} + +impl Default for MutableTree { + fn default() -> Self { + Self::new() + } +} + +impl fmt::Display for MutableTree { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("MutableTree") + } +} diff --git a/rust-bindings/src/auto/remote.rs b/rust-bindings/src/auto/remote.rs new file mode 100644 index 0000000000..95939f25d4 --- /dev/null +++ b/rust-bindings/src/auto/remote.rs @@ -0,0 +1,34 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use glib::translate::*; + +glib::wrapper! { + #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] + pub struct Remote(Shared<ffi::OstreeRemote>); + + match fn { + ref => |ptr| ffi::ostree_remote_ref(ptr), + unref => |ptr| ffi::ostree_remote_unref(ptr), + type_ => || ffi::ostree_remote_get_type(), + } +} + +impl Remote { + #[doc(alias = "ostree_remote_get_name")] + #[doc(alias = "get_name")] + pub fn name(&self) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_remote_get_name(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_remote_get_url")] + #[doc(alias = "get_url")] + pub fn url(&self) -> Option<glib::GString> { + unsafe { + from_glib_full(ffi::ostree_remote_get_url(self.to_glib_none().0)) + } + } +} diff --git a/rust-bindings/src/auto/repo.rs b/rust-bindings/src/auto/repo.rs new file mode 100644 index 0000000000..84c5bd07ac --- /dev/null +++ b/rust-bindings/src/auto/repo.rs @@ -0,0 +1,1350 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use crate::AsyncProgress; +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +use crate::CollectionRef; +#[cfg(any(feature = "v2021_2", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_2")))] +use crate::ContentWriter; +use crate::GpgVerifyResult; +use crate::MutableTree; +use crate::ObjectType; +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +use crate::Remote; +#[cfg(any(feature = "v2016_8", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_8")))] +use crate::RepoCheckoutAtOptions; +use crate::RepoCheckoutMode; +use crate::RepoCheckoutOverwriteMode; +use crate::RepoCommitModifier; +#[cfg(any(feature = "v2015_7", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2015_7")))] +use crate::RepoCommitState; +use crate::RepoFile; +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +use crate::RepoFinderResult; +use crate::RepoMode; +use crate::RepoPruneFlags; +use crate::RepoPullFlags; +use crate::RepoRemoteChange; +#[cfg(any(feature = "v2016_7", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_7")))] +use crate::RepoResolveRevExtFlags; +use crate::RepoTransactionStats; +#[cfg(any(feature = "v2021_4", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_4")))] +use crate::RepoVerifyFlags; +#[cfg(any(feature = "v2020_7", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_7")))] +use crate::Sign; +use crate::StaticDeltaGenerateOpt; +use glib::object::IsA; +use glib::object::ObjectType as ObjectType_; +use glib::signal::connect_raw; +use glib::signal::SignalHandlerId; +use glib::translate::*; +use glib::StaticType; +use std::boxed::Box as Box_; +use std::fmt; +use std::mem; +use std::mem::transmute; +use std::ptr; + +glib::wrapper! { + #[doc(alias = "OstreeRepo")] + pub struct Repo(Object<ffi::OstreeRepo>); + + match fn { + type_ => || ffi::ostree_repo_get_type(), + } +} + +impl Repo { + #[doc(alias = "ostree_repo_new")] + pub fn new<P: IsA<gio::File>>(path: &P) -> Repo { + unsafe { + from_glib_full(ffi::ostree_repo_new(path.as_ref().to_glib_none().0)) + } + } + + #[doc(alias = "ostree_repo_new_default")] + pub fn new_default() -> Repo { + unsafe { + from_glib_full(ffi::ostree_repo_new_default()) + } + } + + #[doc(alias = "ostree_repo_new_for_sysroot_path")] + #[doc(alias = "new_for_sysroot_path")] + pub fn for_sysroot_path<P: IsA<gio::File>, Q: IsA<gio::File>>(repo_path: &P, sysroot_path: &Q) -> Repo { + unsafe { + from_glib_full(ffi::ostree_repo_new_for_sysroot_path(repo_path.as_ref().to_glib_none().0, sysroot_path.as_ref().to_glib_none().0)) + } + } + + #[doc(alias = "ostree_repo_abort_transaction")] + pub fn abort_transaction<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_abort_transaction(self.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_add_gpg_signature_summary")] + pub fn add_gpg_signature_summary<P: IsA<gio::Cancellable>>(&self, key_id: &[&str], homedir: Option<&str>, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_add_gpg_signature_summary(self.to_glib_none().0, key_id.to_glib_none().0, homedir.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_append_gpg_signature")] + pub fn append_gpg_signature<P: IsA<gio::Cancellable>>(&self, commit_checksum: &str, signature_bytes: &glib::Bytes, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_append_gpg_signature(self.to_glib_none().0, commit_checksum.to_glib_none().0, signature_bytes.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2016_8", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_8")))] + #[doc(alias = "ostree_repo_checkout_at")] + pub fn checkout_at<P: AsRef<std::path::Path>, Q: IsA<gio::Cancellable>>(&self, options: Option<&RepoCheckoutAtOptions>, destination_dfd: i32, destination_path: P, commit: &str, cancellable: Option<&Q>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_checkout_at(self.to_glib_none().0, mut_override(options.to_glib_none().0), destination_dfd, destination_path.as_ref().to_glib_none().0, commit.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_checkout_gc")] + pub fn checkout_gc<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_checkout_gc(self.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_checkout_tree")] + pub fn checkout_tree<P: IsA<gio::File>, Q: IsA<gio::Cancellable>>(&self, mode: RepoCheckoutMode, overwrite_mode: RepoCheckoutOverwriteMode, destination: &P, source: &RepoFile, source_info: &gio::FileInfo, cancellable: Option<&Q>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_checkout_tree(self.to_glib_none().0, mode.into_glib(), overwrite_mode.into_glib(), destination.as_ref().to_glib_none().0, source.to_glib_none().0, source_info.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_commit_transaction")] + pub fn commit_transaction<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<RepoTransactionStats, glib::Error> { + unsafe { + let mut out_stats = RepoTransactionStats::uninitialized(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_commit_transaction(self.to_glib_none().0, out_stats.to_glib_none_mut().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(out_stats) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_copy_config")] + pub fn copy_config(&self) -> Option<glib::KeyFile> { + unsafe { + from_glib_full(ffi::ostree_repo_copy_config(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_repo_create")] + pub fn create<P: IsA<gio::Cancellable>>(&self, mode: RepoMode, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_create(self.to_glib_none().0, mode.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_delete_object")] + pub fn delete_object<P: IsA<gio::Cancellable>>(&self, objtype: ObjectType, sha256: &str, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_delete_object(self.to_glib_none().0, objtype.into_glib(), sha256.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2017_12", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_12")))] + #[doc(alias = "ostree_repo_equal")] + pub fn equal(&self, b: &Repo) -> bool { + unsafe { + from_glib(ffi::ostree_repo_equal(self.to_glib_none().0, b.to_glib_none().0)) + } + } + + //#[doc(alias = "ostree_repo_export_tree_to_archive")] + //pub fn export_tree_to_archive<P: IsA<gio::Cancellable>>(&self, opts: /*Ignored*/&mut RepoExportArchiveOptions, root: &RepoFile, archive: /*Unimplemented*/Option<Fundamental: Pointer>, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_export_tree_to_archive() } + //} + + #[cfg(any(feature = "v2017_15", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_15")))] + #[doc(alias = "ostree_repo_fsck_object")] + pub fn fsck_object<P: IsA<gio::Cancellable>>(&self, objtype: ObjectType, sha256: &str, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_fsck_object(self.to_glib_none().0, objtype.into_glib(), sha256.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2019_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_2")))] + #[doc(alias = "ostree_repo_get_bootloader")] + #[doc(alias = "get_bootloader")] + pub fn bootloader(&self) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_repo_get_bootloader(self.to_glib_none().0)) + } + } + + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + #[doc(alias = "ostree_repo_get_collection_id")] + #[doc(alias = "get_collection_id")] + pub fn collection_id(&self) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_repo_get_collection_id(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_repo_get_config")] + #[doc(alias = "get_config")] + pub fn config(&self) -> Option<glib::KeyFile> { + unsafe { + from_glib_none(ffi::ostree_repo_get_config(self.to_glib_none().0)) + } + } + + #[cfg(any(feature = "v2018_9", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_9")))] + #[doc(alias = "ostree_repo_get_default_repo_finders")] + #[doc(alias = "get_default_repo_finders")] + pub fn default_repo_finders(&self) -> Vec<glib::GString> { + unsafe { + FromGlibPtrContainer::from_glib_none(ffi::ostree_repo_get_default_repo_finders(self.to_glib_none().0)) + } + } + + #[cfg(any(feature = "v2016_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] + #[doc(alias = "ostree_repo_get_dfd")] + #[doc(alias = "get_dfd")] + pub fn dfd(&self) -> i32 { + unsafe { + ffi::ostree_repo_get_dfd(self.to_glib_none().0) + } + } + + #[doc(alias = "ostree_repo_get_disable_fsync")] + #[doc(alias = "get_disable_fsync")] + pub fn is_disable_fsync(&self) -> bool { + unsafe { + from_glib(ffi::ostree_repo_get_disable_fsync(self.to_glib_none().0)) + } + } + + #[cfg(any(feature = "v2018_9", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_9")))] + #[doc(alias = "ostree_repo_get_min_free_space_bytes")] + #[doc(alias = "get_min_free_space_bytes")] + pub fn min_free_space_bytes(&self) -> Result<u64, glib::Error> { + unsafe { + let mut out_reserved_bytes = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_get_min_free_space_bytes(self.to_glib_none().0, out_reserved_bytes.as_mut_ptr(), &mut error); + let out_reserved_bytes = out_reserved_bytes.assume_init(); + if error.is_null() { Ok(out_reserved_bytes) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_get_mode")] + #[doc(alias = "get_mode")] + pub fn mode(&self) -> RepoMode { + unsafe { + from_glib(ffi::ostree_repo_get_mode(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_repo_get_parent")] + #[doc(alias = "get_parent")] + pub fn parent(&self) -> Option<Repo> { + unsafe { + from_glib_none(ffi::ostree_repo_get_parent(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_repo_get_path")] + #[doc(alias = "get_path")] + pub fn path(&self) -> Option<gio::File> { + unsafe { + from_glib_none(ffi::ostree_repo_get_path(self.to_glib_none().0)) + } + } + + #[cfg(any(feature = "v2016_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_5")))] + #[doc(alias = "ostree_repo_get_remote_boolean_option")] + #[doc(alias = "get_remote_boolean_option")] + pub fn remote_boolean_option(&self, remote_name: &str, option_name: &str, default_value: bool) -> Result<bool, glib::Error> { + unsafe { + let mut out_value = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_get_remote_boolean_option(self.to_glib_none().0, remote_name.to_glib_none().0, option_name.to_glib_none().0, default_value.into_glib(), out_value.as_mut_ptr(), &mut error); + let out_value = out_value.assume_init(); + if error.is_null() { Ok(from_glib(out_value)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2016_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_5")))] + #[doc(alias = "ostree_repo_get_remote_list_option")] + #[doc(alias = "get_remote_list_option")] + pub fn remote_list_option(&self, remote_name: &str, option_name: &str) -> Result<Vec<glib::GString>, glib::Error> { + unsafe { + let mut out_value = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_get_remote_list_option(self.to_glib_none().0, remote_name.to_glib_none().0, option_name.to_glib_none().0, &mut out_value, &mut error); + if error.is_null() { Ok(FromGlibPtrContainer::from_glib_full(out_value)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2016_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_5")))] + #[doc(alias = "ostree_repo_get_remote_option")] + #[doc(alias = "get_remote_option")] + pub fn remote_option(&self, remote_name: &str, option_name: &str, default_value: Option<&str>) -> Result<glib::GString, glib::Error> { + unsafe { + let mut out_value = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_get_remote_option(self.to_glib_none().0, remote_name.to_glib_none().0, option_name.to_glib_none().0, default_value.to_glib_none().0, &mut out_value, &mut error); + if error.is_null() { Ok(from_glib_full(out_value)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2020_8", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_8")))] + #[doc(alias = "ostree_repo_gpg_sign_data")] + pub fn gpg_sign_data<P: IsA<gio::Cancellable>>(&self, data: &glib::Bytes, old_signatures: &glib::Bytes, key_id: &[&str], homedir: Option<&str>, cancellable: Option<&P>) -> Result<glib::Bytes, glib::Error> { + unsafe { + let mut out_signatures = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_gpg_sign_data(self.to_glib_none().0, data.to_glib_none().0, old_signatures.to_glib_none().0, key_id.to_glib_none().0, homedir.to_glib_none().0, &mut out_signatures, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_signatures)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2016_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_6")))] + #[doc(alias = "ostree_repo_gpg_verify_data")] + pub fn gpg_verify_data<P: IsA<gio::File>, Q: IsA<gio::File>, R: IsA<gio::Cancellable>>(&self, remote_name: Option<&str>, data: &glib::Bytes, signatures: &glib::Bytes, keyringdir: Option<&P>, extra_keyring: Option<&Q>, cancellable: Option<&R>) -> Result<GpgVerifyResult, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_repo_gpg_verify_data(self.to_glib_none().0, remote_name.to_glib_none().0, data.to_glib_none().0, signatures.to_glib_none().0, keyringdir.map(|p| p.as_ref()).to_glib_none().0, extra_keyring.map(|p| p.as_ref()).to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_has_object")] + pub fn has_object<P: IsA<gio::Cancellable>>(&self, objtype: ObjectType, checksum: &str, cancellable: Option<&P>) -> Result<bool, glib::Error> { + unsafe { + let mut out_have_object = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_has_object(self.to_glib_none().0, objtype.into_glib(), checksum.to_glib_none().0, out_have_object.as_mut_ptr(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + let out_have_object = out_have_object.assume_init(); + if error.is_null() { Ok(from_glib(out_have_object)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2017_12", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_12")))] + #[doc(alias = "ostree_repo_hash")] + pub fn hash(&self) -> u32 { + unsafe { + ffi::ostree_repo_hash(self.to_glib_none().0) + } + } + + //#[doc(alias = "ostree_repo_import_archive_to_mtree")] + //pub fn import_archive_to_mtree<P: IsA<gio::Cancellable>>(&self, opts: /*Ignored*/&mut RepoImportArchiveOptions, archive: /*Unimplemented*/Option<Fundamental: Pointer>, mtree: &MutableTree, modifier: Option<&RepoCommitModifier>, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_import_archive_to_mtree() } + //} + + #[doc(alias = "ostree_repo_import_object_from")] + pub fn import_object_from<P: IsA<gio::Cancellable>>(&self, source: &Repo, objtype: ObjectType, checksum: &str, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_import_object_from(self.to_glib_none().0, source.to_glib_none().0, objtype.into_glib(), checksum.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2016_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_5")))] + #[doc(alias = "ostree_repo_import_object_from_with_trust")] + pub fn import_object_from_with_trust<P: IsA<gio::Cancellable>>(&self, source: &Repo, objtype: ObjectType, checksum: &str, trusted: bool, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_import_object_from_with_trust(self.to_glib_none().0, source.to_glib_none().0, objtype.into_glib(), checksum.to_glib_none().0, trusted.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_is_system")] + pub fn is_system(&self) -> bool { + unsafe { + from_glib(ffi::ostree_repo_is_system(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_repo_is_writable")] + pub fn is_writable(&self) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_is_writable(self.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + //#[cfg(any(feature = "v2018_6", feature = "dox"))] + //#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + //#[doc(alias = "ostree_repo_list_collection_refs")] + //pub fn list_collection_refs<P: IsA<gio::Cancellable>>(&self, match_collection_id: Option<&str>, out_all_refs: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 1, id: 0 }/TypeId { ns_id: 0, id: 28 }, flags: RepoListRefsExtFlags, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_list_collection_refs() } + //} + + //#[doc(alias = "ostree_repo_list_commit_objects_starting_with")] + //pub fn list_commit_objects_starting_with<P: IsA<gio::Cancellable>>(&self, start: &str, out_commits: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 2, id: 194 }/TypeId { ns_id: 2, id: 194 }, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_list_commit_objects_starting_with() } + //} + + //#[doc(alias = "ostree_repo_list_objects")] + //pub fn list_objects<P: IsA<gio::Cancellable>>(&self, flags: RepoListObjectsFlags, out_objects: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 2, id: 194 }/TypeId { ns_id: 2, id: 194 }, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_list_objects() } + //} + + //#[doc(alias = "ostree_repo_list_refs")] + //pub fn list_refs<P: IsA<gio::Cancellable>>(&self, refspec_prefix: Option<&str>, out_all_refs: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 }, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_list_refs() } + //} + + //#[cfg(any(feature = "v2016_4", feature = "dox"))] + //#[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] + //#[doc(alias = "ostree_repo_list_refs_ext")] + //pub fn list_refs_ext<P: IsA<gio::Cancellable>>(&self, refspec_prefix: Option<&str>, out_all_refs: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 }, flags: RepoListRefsExtFlags, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_list_refs_ext() } + //} + + #[cfg(any(feature = "v2020_8", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_8")))] + #[doc(alias = "ostree_repo_list_static_delta_indexes")] + pub fn list_static_delta_indexes<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<Vec<glib::GString>, glib::Error> { + unsafe { + let mut out_indexes = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_list_static_delta_indexes(self.to_glib_none().0, &mut out_indexes, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(FromGlibPtrContainer::from_glib_container(out_indexes)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_list_static_delta_names")] + pub fn list_static_delta_names<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<Vec<glib::GString>, glib::Error> { + unsafe { + let mut out_deltas = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_list_static_delta_names(self.to_glib_none().0, &mut out_deltas, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(FromGlibPtrContainer::from_glib_container(out_deltas)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2015_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2015_7")))] + #[doc(alias = "ostree_repo_load_commit")] + pub fn load_commit(&self, checksum: &str) -> Result<(glib::Variant, RepoCommitState), glib::Error> { + unsafe { + let mut out_commit = ptr::null_mut(); + let mut out_state = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_load_commit(self.to_glib_none().0, checksum.to_glib_none().0, &mut out_commit, out_state.as_mut_ptr(), &mut error); + let out_state = out_state.assume_init(); + if error.is_null() { Ok((from_glib_full(out_commit), from_glib(out_state))) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_load_file")] + pub fn load_file<P: IsA<gio::Cancellable>>(&self, checksum: &str, cancellable: Option<&P>) -> Result<(Option<gio::InputStream>, Option<gio::FileInfo>, Option<glib::Variant>), glib::Error> { + unsafe { + let mut out_input = ptr::null_mut(); + let mut out_file_info = ptr::null_mut(); + let mut out_xattrs = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_load_file(self.to_glib_none().0, checksum.to_glib_none().0, &mut out_input, &mut out_file_info, &mut out_xattrs, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok((from_glib_full(out_input), from_glib_full(out_file_info), from_glib_full(out_xattrs))) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_load_object_stream")] + pub fn load_object_stream<P: IsA<gio::Cancellable>>(&self, objtype: ObjectType, checksum: &str, cancellable: Option<&P>) -> Result<(gio::InputStream, u64), glib::Error> { + unsafe { + let mut out_input = ptr::null_mut(); + let mut out_size = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_load_object_stream(self.to_glib_none().0, objtype.into_glib(), checksum.to_glib_none().0, &mut out_input, out_size.as_mut_ptr(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + let out_size = out_size.assume_init(); + if error.is_null() { Ok((from_glib_full(out_input), out_size)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_load_variant")] + pub fn load_variant(&self, objtype: ObjectType, sha256: &str) -> Result<glib::Variant, glib::Error> { + unsafe { + let mut out_variant = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_load_variant(self.to_glib_none().0, objtype.into_glib(), sha256.to_glib_none().0, &mut out_variant, &mut error); + if error.is_null() { Ok(from_glib_full(out_variant)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_load_variant_if_exists")] + pub fn load_variant_if_exists(&self, objtype: ObjectType, sha256: &str) -> Result<Option<glib::Variant>, glib::Error> { + unsafe { + let mut out_variant = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_load_variant_if_exists(self.to_glib_none().0, objtype.into_glib(), sha256.to_glib_none().0, &mut out_variant, &mut error); + if error.is_null() { Ok(from_glib_full(out_variant)) } else { Err(from_glib_full(error)) } + } + } + + //#[cfg(any(feature = "v2021_3", feature = "dox"))] + //#[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_3")))] + //#[doc(alias = "ostree_repo_lock_pop")] + //pub fn lock_pop<P: IsA<gio::Cancellable>>(&self, lock_type: /*Ignored*/RepoLockType, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_lock_pop() } + //} + + //#[cfg(any(feature = "v2021_3", feature = "dox"))] + //#[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_3")))] + //#[doc(alias = "ostree_repo_lock_push")] + //pub fn lock_push<P: IsA<gio::Cancellable>>(&self, lock_type: /*Ignored*/RepoLockType, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_lock_push() } + //} + + #[cfg(any(feature = "v2017_15", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_15")))] + #[doc(alias = "ostree_repo_mark_commit_partial")] + pub fn mark_commit_partial(&self, checksum: &str, is_partial: bool) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_mark_commit_partial(self.to_glib_none().0, checksum.to_glib_none().0, is_partial.into_glib(), &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2019_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_4")))] + #[doc(alias = "ostree_repo_mark_commit_partial_reason")] + pub fn mark_commit_partial_reason(&self, checksum: &str, is_partial: bool, in_state: RepoCommitState) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_mark_commit_partial_reason(self.to_glib_none().0, checksum.to_glib_none().0, is_partial.into_glib(), in_state.into_glib(), &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_open")] + pub fn open<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_open(self.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_prepare_transaction")] + pub fn prepare_transaction<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<bool, glib::Error> { + unsafe { + let mut out_transaction_resume = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_prepare_transaction(self.to_glib_none().0, out_transaction_resume.as_mut_ptr(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + let out_transaction_resume = out_transaction_resume.assume_init(); + if error.is_null() { Ok(from_glib(out_transaction_resume)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_prune")] + pub fn prune<P: IsA<gio::Cancellable>>(&self, flags: RepoPruneFlags, depth: i32, cancellable: Option<&P>) -> Result<(i32, i32, u64), glib::Error> { + unsafe { + let mut out_objects_total = mem::MaybeUninit::uninit(); + let mut out_objects_pruned = mem::MaybeUninit::uninit(); + let mut out_pruned_object_size_total = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_prune(self.to_glib_none().0, flags.into_glib(), depth, out_objects_total.as_mut_ptr(), out_objects_pruned.as_mut_ptr(), out_pruned_object_size_total.as_mut_ptr(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + let out_objects_total = out_objects_total.assume_init(); + let out_objects_pruned = out_objects_pruned.assume_init(); + let out_pruned_object_size_total = out_pruned_object_size_total.assume_init(); + if error.is_null() { Ok((out_objects_total, out_objects_pruned, out_pruned_object_size_total)) } else { Err(from_glib_full(error)) } + } + } + + //#[cfg(any(feature = "v2017_1", feature = "dox"))] + //#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_1")))] + //#[doc(alias = "ostree_repo_prune_from_reachable")] + //pub fn prune_from_reachable<P: IsA<gio::Cancellable>>(&self, options: /*Ignored*/&mut RepoPruneOptions, cancellable: Option<&P>) -> Result<(i32, i32, u64), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_prune_from_reachable() } + //} + + #[doc(alias = "ostree_repo_prune_static_deltas")] + pub fn prune_static_deltas<P: IsA<gio::Cancellable>>(&self, commit: Option<&str>, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_prune_static_deltas(self.to_glib_none().0, commit.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_pull")] + pub fn pull<P: IsA<gio::Cancellable>>(&self, remote_name: &str, refs_to_fetch: &[&str], flags: RepoPullFlags, progress: Option<&AsyncProgress>, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_pull(self.to_glib_none().0, remote_name.to_glib_none().0, refs_to_fetch.to_glib_none().0, flags.into_glib(), progress.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_pull_one_dir")] + pub fn pull_one_dir<P: IsA<gio::Cancellable>>(&self, remote_name: &str, dir_to_pull: &str, refs_to_fetch: &[&str], flags: RepoPullFlags, progress: Option<&AsyncProgress>, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_pull_one_dir(self.to_glib_none().0, remote_name.to_glib_none().0, dir_to_pull.to_glib_none().0, refs_to_fetch.to_glib_none().0, flags.into_glib(), progress.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_pull_with_options")] + pub fn pull_with_options<P: IsA<gio::Cancellable>>(&self, remote_name_or_baseurl: &str, options: &glib::Variant, progress: Option<&AsyncProgress>, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_pull_with_options(self.to_glib_none().0, remote_name_or_baseurl.to_glib_none().0, options.to_glib_none().0, progress.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_query_object_storage_size")] + pub fn query_object_storage_size<P: IsA<gio::Cancellable>>(&self, objtype: ObjectType, sha256: &str, cancellable: Option<&P>) -> Result<u64, glib::Error> { + unsafe { + let mut out_size = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_query_object_storage_size(self.to_glib_none().0, objtype.into_glib(), sha256.to_glib_none().0, out_size.as_mut_ptr(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + let out_size = out_size.assume_init(); + if error.is_null() { Ok(out_size) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_read_commit")] + pub fn read_commit<P: IsA<gio::Cancellable>>(&self, ref_: &str, cancellable: Option<&P>) -> Result<(gio::File, glib::GString), glib::Error> { + unsafe { + let mut out_root = ptr::null_mut(); + let mut out_commit = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_read_commit(self.to_glib_none().0, ref_.to_glib_none().0, &mut out_root, &mut out_commit, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok((from_glib_full(out_root), from_glib_full(out_commit))) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_read_commit_detached_metadata")] + pub fn read_commit_detached_metadata<P: IsA<gio::Cancellable>>(&self, checksum: &str, cancellable: Option<&P>) -> Result<Option<glib::Variant>, glib::Error> { + unsafe { + let mut out_metadata = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_read_commit_detached_metadata(self.to_glib_none().0, checksum.to_glib_none().0, &mut out_metadata, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_metadata)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_regenerate_summary")] + pub fn regenerate_summary<P: IsA<gio::Cancellable>>(&self, additional_metadata: Option<&glib::Variant>, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_regenerate_summary(self.to_glib_none().0, additional_metadata.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2017_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_2")))] + #[doc(alias = "ostree_repo_reload_config")] + pub fn reload_config<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_reload_config(self.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_remote_add")] + pub fn remote_add<P: IsA<gio::Cancellable>>(&self, name: &str, url: Option<&str>, options: Option<&glib::Variant>, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_remote_add(self.to_glib_none().0, name.to_glib_none().0, url.to_glib_none().0, options.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_remote_change")] + pub fn remote_change<P: IsA<gio::File>, Q: IsA<gio::Cancellable>>(&self, sysroot: Option<&P>, changeop: RepoRemoteChange, name: &str, url: Option<&str>, options: Option<&glib::Variant>, cancellable: Option<&Q>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_remote_change(self.to_glib_none().0, sysroot.map(|p| p.as_ref()).to_glib_none().0, changeop.into_glib(), name.to_glib_none().0, url.to_glib_none().0, options.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_remote_delete")] + pub fn remote_delete<P: IsA<gio::Cancellable>>(&self, name: &str, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_remote_delete(self.to_glib_none().0, name.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_remote_fetch_summary")] + pub fn remote_fetch_summary<P: IsA<gio::Cancellable>>(&self, name: &str, cancellable: Option<&P>) -> Result<(glib::Bytes, glib::Bytes), glib::Error> { + unsafe { + let mut out_summary = ptr::null_mut(); + let mut out_signatures = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_remote_fetch_summary(self.to_glib_none().0, name.to_glib_none().0, &mut out_summary, &mut out_signatures, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok((from_glib_full(out_summary), from_glib_full(out_signatures))) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2016_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_6")))] + #[doc(alias = "ostree_repo_remote_fetch_summary_with_options")] + pub fn remote_fetch_summary_with_options<P: IsA<gio::Cancellable>>(&self, name: &str, options: Option<&glib::Variant>, cancellable: Option<&P>) -> Result<(glib::Bytes, glib::Bytes), glib::Error> { + unsafe { + let mut out_summary = ptr::null_mut(); + let mut out_signatures = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_remote_fetch_summary_with_options(self.to_glib_none().0, name.to_glib_none().0, options.to_glib_none().0, &mut out_summary, &mut out_signatures, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok((from_glib_full(out_summary), from_glib_full(out_signatures))) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2021_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_4")))] + #[doc(alias = "ostree_repo_remote_get_gpg_keys")] + pub fn remote_get_gpg_keys<P: IsA<gio::Cancellable>>(&self, name: Option<&str>, key_ids: &[&str], cancellable: Option<&P>) -> Result<Vec<glib::Variant>, glib::Error> { + unsafe { + let mut out_keys = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_remote_get_gpg_keys(self.to_glib_none().0, name.to_glib_none().0, key_ids.to_glib_none().0, &mut out_keys, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(FromGlibPtrContainer::from_glib_container(out_keys)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_remote_get_gpg_verify")] + pub fn remote_get_gpg_verify(&self, name: &str) -> Result<bool, glib::Error> { + unsafe { + let mut out_gpg_verify = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_remote_get_gpg_verify(self.to_glib_none().0, name.to_glib_none().0, out_gpg_verify.as_mut_ptr(), &mut error); + let out_gpg_verify = out_gpg_verify.assume_init(); + if error.is_null() { Ok(from_glib(out_gpg_verify)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_remote_get_gpg_verify_summary")] + pub fn remote_get_gpg_verify_summary(&self, name: &str) -> Result<bool, glib::Error> { + unsafe { + let mut out_gpg_verify_summary = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_remote_get_gpg_verify_summary(self.to_glib_none().0, name.to_glib_none().0, out_gpg_verify_summary.as_mut_ptr(), &mut error); + let out_gpg_verify_summary = out_gpg_verify_summary.assume_init(); + if error.is_null() { Ok(from_glib(out_gpg_verify_summary)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_remote_get_url")] + pub fn remote_get_url(&self, name: &str) -> Result<glib::GString, glib::Error> { + unsafe { + let mut out_url = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_remote_get_url(self.to_glib_none().0, name.to_glib_none().0, &mut out_url, &mut error); + if error.is_null() { Ok(from_glib_full(out_url)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_remote_gpg_import")] + pub fn remote_gpg_import<P: IsA<gio::InputStream>, Q: IsA<gio::Cancellable>>(&self, name: &str, source_stream: Option<&P>, key_ids: &[&str], cancellable: Option<&Q>) -> Result<u32, glib::Error> { + unsafe { + let mut out_imported = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_remote_gpg_import(self.to_glib_none().0, name.to_glib_none().0, source_stream.map(|p| p.as_ref()).to_glib_none().0, key_ids.to_glib_none().0, out_imported.as_mut_ptr(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + let out_imported = out_imported.assume_init(); + if error.is_null() { Ok(out_imported) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_remote_list")] + pub fn remote_list(&self) -> Vec<glib::GString> { + unsafe { + let mut out_n_remotes = mem::MaybeUninit::uninit(); + let ret = FromGlibContainer::from_glib_full_num(ffi::ostree_repo_remote_list(self.to_glib_none().0, out_n_remotes.as_mut_ptr()), out_n_remotes.assume_init() as usize); + ret + } + } + + //#[cfg(any(feature = "v2018_6", feature = "dox"))] + //#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + //#[doc(alias = "ostree_repo_remote_list_collection_refs")] + //pub fn remote_list_collection_refs<P: IsA<gio::Cancellable>>(&self, remote_name: &str, out_all_refs: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 1, id: 0 }/TypeId { ns_id: 0, id: 28 }, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_remote_list_collection_refs() } + //} + + //#[doc(alias = "ostree_repo_remote_list_refs")] + //pub fn remote_list_refs<P: IsA<gio::Cancellable>>(&self, remote_name: &str, out_all_refs: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 }, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_remote_list_refs() } + //} + + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + #[doc(alias = "ostree_repo_resolve_collection_ref")] + pub fn resolve_collection_ref<P: IsA<gio::Cancellable>>(&self, ref_: &CollectionRef, allow_noent: bool, flags: RepoResolveRevExtFlags, cancellable: Option<&P>) -> Result<Option<glib::GString>, glib::Error> { + unsafe { + let mut out_rev = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_resolve_collection_ref(self.to_glib_none().0, ref_.to_glib_none().0, allow_noent.into_glib(), flags.into_glib(), &mut out_rev, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_rev)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + #[doc(alias = "ostree_repo_resolve_keyring_for_collection")] + pub fn resolve_keyring_for_collection<P: IsA<gio::Cancellable>>(&self, collection_id: &str, cancellable: Option<&P>) -> Result<Remote, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_repo_resolve_keyring_for_collection(self.to_glib_none().0, collection_id.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_resolve_rev")] + pub fn resolve_rev(&self, refspec: &str, allow_noent: bool) -> Result<Option<glib::GString>, glib::Error> { + unsafe { + let mut out_rev = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_resolve_rev(self.to_glib_none().0, refspec.to_glib_none().0, allow_noent.into_glib(), &mut out_rev, &mut error); + if error.is_null() { Ok(from_glib_full(out_rev)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2016_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_7")))] + #[doc(alias = "ostree_repo_resolve_rev_ext")] + pub fn resolve_rev_ext(&self, refspec: &str, allow_noent: bool, flags: RepoResolveRevExtFlags) -> Result<Option<glib::GString>, glib::Error> { + unsafe { + let mut out_rev = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_resolve_rev_ext(self.to_glib_none().0, refspec.to_glib_none().0, allow_noent.into_glib(), flags.into_glib(), &mut out_rev, &mut error); + if error.is_null() { Ok(from_glib_full(out_rev)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_scan_hardlinks")] + pub fn scan_hardlinks<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_scan_hardlinks(self.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2017_10", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_10")))] + #[doc(alias = "ostree_repo_set_alias_ref_immediate")] + pub fn set_alias_ref_immediate<P: IsA<gio::Cancellable>>(&self, remote: Option<&str>, ref_: &str, target: Option<&str>, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_set_alias_ref_immediate(self.to_glib_none().0, remote.to_glib_none().0, ref_.to_glib_none().0, target.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2016_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_5")))] + #[doc(alias = "ostree_repo_set_cache_dir")] + pub fn set_cache_dir<P: IsA<gio::Cancellable>>(&self, dfd: i32, path: &str, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_set_cache_dir(self.to_glib_none().0, dfd, path.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + #[doc(alias = "ostree_repo_set_collection_id")] + pub fn set_collection_id(&self, collection_id: Option<&str>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_set_collection_id(self.to_glib_none().0, collection_id.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + #[doc(alias = "ostree_repo_set_collection_ref_immediate")] + pub fn set_collection_ref_immediate<P: IsA<gio::Cancellable>>(&self, ref_: &CollectionRef, checksum: Option<&str>, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_set_collection_ref_immediate(self.to_glib_none().0, ref_.to_glib_none().0, checksum.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_set_disable_fsync")] + pub fn set_disable_fsync(&self, disable_fsync: bool) { + unsafe { + ffi::ostree_repo_set_disable_fsync(self.to_glib_none().0, disable_fsync.into_glib()); + } + } + + #[doc(alias = "ostree_repo_set_ref_immediate")] + pub fn set_ref_immediate<P: IsA<gio::Cancellable>>(&self, remote: Option<&str>, ref_: &str, checksum: Option<&str>, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_set_ref_immediate(self.to_glib_none().0, remote.to_glib_none().0, ref_.to_glib_none().0, checksum.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_sign_commit")] + pub fn sign_commit<P: IsA<gio::Cancellable>>(&self, commit_checksum: &str, key_id: &str, homedir: Option<&str>, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_sign_commit(self.to_glib_none().0, commit_checksum.to_glib_none().0, key_id.to_glib_none().0, homedir.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_sign_delta")] + pub fn sign_delta<P: IsA<gio::Cancellable>>(&self, from_commit: &str, to_commit: &str, key_id: &str, homedir: &str, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_sign_delta(self.to_glib_none().0, from_commit.to_glib_none().0, to_commit.to_glib_none().0, key_id.to_glib_none().0, homedir.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2021_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_4")))] + #[doc(alias = "ostree_repo_signature_verify_commit_data")] + pub fn signature_verify_commit_data(&self, remote_name: &str, commit_data: &glib::Bytes, commit_metadata: &glib::Bytes, flags: RepoVerifyFlags) -> Result<Option<glib::GString>, glib::Error> { + unsafe { + let mut out_results = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_signature_verify_commit_data(self.to_glib_none().0, remote_name.to_glib_none().0, commit_data.to_glib_none().0, commit_metadata.to_glib_none().0, flags.into_glib(), &mut out_results, &mut error); + if error.is_null() { Ok(from_glib_full(out_results)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_static_delta_execute_offline")] + pub fn static_delta_execute_offline<P: IsA<gio::File>, Q: IsA<gio::Cancellable>>(&self, dir_or_file: &P, skip_validation: bool, cancellable: Option<&Q>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_static_delta_execute_offline(self.to_glib_none().0, dir_or_file.as_ref().to_glib_none().0, skip_validation.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2020_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_7")))] + #[doc(alias = "ostree_repo_static_delta_execute_offline_with_signature")] + pub fn static_delta_execute_offline_with_signature<P: IsA<gio::File>, Q: IsA<Sign>, R: IsA<gio::Cancellable>>(&self, dir_or_file: &P, sign: &Q, skip_validation: bool, cancellable: Option<&R>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_static_delta_execute_offline_with_signature(self.to_glib_none().0, dir_or_file.as_ref().to_glib_none().0, sign.as_ref().to_glib_none().0, skip_validation.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_static_delta_generate")] + pub fn static_delta_generate<P: IsA<gio::Cancellable>>(&self, opt: StaticDeltaGenerateOpt, from: Option<&str>, to: &str, metadata: Option<&glib::Variant>, params: Option<&glib::Variant>, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_static_delta_generate(self.to_glib_none().0, opt.into_glib(), from.to_glib_none().0, to.to_glib_none().0, metadata.to_glib_none().0, params.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + //#[cfg(any(feature = "v2020_8", feature = "dox"))] + //#[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_8")))] + //#[doc(alias = "ostree_repo_static_delta_reindex")] + //pub fn static_delta_reindex<P: IsA<gio::Cancellable>>(&self, flags: /*Ignored*/StaticDeltaIndexFlags, opt_to_commit: &str, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_static_delta_reindex() } + //} + + #[cfg(any(feature = "v2020_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_7")))] + #[doc(alias = "ostree_repo_static_delta_verify_signature")] + pub fn static_delta_verify_signature<P: IsA<Sign>>(&self, delta_id: &str, sign: &P) -> Result<Option<glib::GString>, glib::Error> { + unsafe { + let mut out_success_message = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_static_delta_verify_signature(self.to_glib_none().0, delta_id.to_glib_none().0, sign.as_ref().to_glib_none().0, &mut out_success_message, &mut error); + if error.is_null() { Ok(from_glib_full(out_success_message)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + #[doc(alias = "ostree_repo_transaction_set_collection_ref")] + pub fn transaction_set_collection_ref(&self, ref_: &CollectionRef, checksum: Option<&str>) { + unsafe { + ffi::ostree_repo_transaction_set_collection_ref(self.to_glib_none().0, ref_.to_glib_none().0, checksum.to_glib_none().0); + } + } + + #[doc(alias = "ostree_repo_transaction_set_ref")] + pub fn transaction_set_ref(&self, remote: Option<&str>, ref_: &str, checksum: Option<&str>) { + unsafe { + ffi::ostree_repo_transaction_set_ref(self.to_glib_none().0, remote.to_glib_none().0, ref_.to_glib_none().0, checksum.to_glib_none().0); + } + } + + #[doc(alias = "ostree_repo_transaction_set_refspec")] + pub fn transaction_set_refspec(&self, refspec: &str, checksum: Option<&str>) { + unsafe { + ffi::ostree_repo_transaction_set_refspec(self.to_glib_none().0, refspec.to_glib_none().0, checksum.to_glib_none().0); + } + } + + //#[doc(alias = "ostree_repo_traverse_commit")] + //pub fn traverse_commit<P: IsA<gio::Cancellable>>(&self, commit_checksum: &str, maxdepth: i32, out_reachable: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 2, id: 194 }/TypeId { ns_id: 2, id: 194 }, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_traverse_commit() } + //} + + //#[doc(alias = "ostree_repo_traverse_commit_union")] + //pub fn traverse_commit_union<P: IsA<gio::Cancellable>>(&self, commit_checksum: &str, maxdepth: i32, inout_reachable: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 25 }/TypeId { ns_id: 0, id: 25 }, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_traverse_commit_union() } + //} + + //#[cfg(any(feature = "v2018_5", feature = "dox"))] + //#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_5")))] + //#[doc(alias = "ostree_repo_traverse_commit_union_with_parents")] + //pub fn traverse_commit_union_with_parents<P: IsA<gio::Cancellable>>(&self, commit_checksum: &str, maxdepth: i32, inout_reachable: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 25 }/TypeId { ns_id: 0, id: 25 }, inout_parents: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 25 }/TypeId { ns_id: 0, id: 25 }, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_traverse_commit_union_with_parents() } + //} + + //#[cfg(any(feature = "v2018_5", feature = "dox"))] + //#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_5")))] + //#[doc(alias = "ostree_repo_traverse_commit_with_flags")] + //pub fn traverse_commit_with_flags<P: IsA<gio::Cancellable>>(&self, flags: RepoCommitTraverseFlags, commit_checksum: &str, maxdepth: i32, inout_reachable: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 25 }/TypeId { ns_id: 0, id: 25 }, inout_parents: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 25 }/TypeId { ns_id: 0, id: 25 }, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_traverse_commit_with_flags() } + //} + + //#[cfg(any(feature = "v2018_6", feature = "dox"))] + //#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + //#[doc(alias = "ostree_repo_traverse_reachable_refs")] + //pub fn traverse_reachable_refs<P: IsA<gio::Cancellable>>(&self, depth: u32, reachable: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 2, id: 194 }/TypeId { ns_id: 2, id: 194 }, cancellable: Option<&P>) -> Result<(), glib::Error> { + // unsafe { TODO: call ffi:ostree_repo_traverse_reachable_refs() } + //} + + #[doc(alias = "ostree_repo_verify_commit")] + pub fn verify_commit<P: IsA<gio::File>, Q: IsA<gio::File>, R: IsA<gio::Cancellable>>(&self, commit_checksum: &str, keyringdir: Option<&P>, extra_keyring: Option<&Q>, cancellable: Option<&R>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_verify_commit(self.to_glib_none().0, commit_checksum.to_glib_none().0, keyringdir.map(|p| p.as_ref()).to_glib_none().0, extra_keyring.map(|p| p.as_ref()).to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_verify_commit_ext")] + pub fn verify_commit_ext<P: IsA<gio::File>, Q: IsA<gio::File>, R: IsA<gio::Cancellable>>(&self, commit_checksum: &str, keyringdir: Option<&P>, extra_keyring: Option<&Q>, cancellable: Option<&R>) -> Result<GpgVerifyResult, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_repo_verify_commit_ext(self.to_glib_none().0, commit_checksum.to_glib_none().0, keyringdir.map(|p| p.as_ref()).to_glib_none().0, extra_keyring.map(|p| p.as_ref()).to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2016_14", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_14")))] + #[doc(alias = "ostree_repo_verify_commit_for_remote")] + pub fn verify_commit_for_remote<P: IsA<gio::Cancellable>>(&self, commit_checksum: &str, remote_name: &str, cancellable: Option<&P>) -> Result<GpgVerifyResult, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_repo_verify_commit_for_remote(self.to_glib_none().0, commit_checksum.to_glib_none().0, remote_name.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_verify_summary")] + pub fn verify_summary<P: IsA<gio::Cancellable>>(&self, remote_name: &str, summary: &glib::Bytes, signatures: &glib::Bytes, cancellable: Option<&P>) -> Result<GpgVerifyResult, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_repo_verify_summary(self.to_glib_none().0, remote_name.to_glib_none().0, summary.to_glib_none().0, signatures.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_write_archive_to_mtree")] + pub fn write_archive_to_mtree<P: IsA<gio::File>, Q: IsA<gio::Cancellable>>(&self, archive: &P, mtree: &MutableTree, modifier: Option<&RepoCommitModifier>, autocreate_parents: bool, cancellable: Option<&Q>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_write_archive_to_mtree(self.to_glib_none().0, archive.as_ref().to_glib_none().0, mtree.to_glib_none().0, modifier.to_glib_none().0, autocreate_parents.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_write_archive_to_mtree_from_fd")] + pub fn write_archive_to_mtree_from_fd<P: IsA<gio::Cancellable>>(&self, fd: i32, mtree: &MutableTree, modifier: Option<&RepoCommitModifier>, autocreate_parents: bool, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_write_archive_to_mtree_from_fd(self.to_glib_none().0, fd, mtree.to_glib_none().0, modifier.to_glib_none().0, autocreate_parents.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_write_commit")] + pub fn write_commit<P: IsA<gio::Cancellable>>(&self, parent: Option<&str>, subject: Option<&str>, body: Option<&str>, metadata: Option<&glib::Variant>, root: &RepoFile, cancellable: Option<&P>) -> Result<glib::GString, glib::Error> { + unsafe { + let mut out_commit = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_write_commit(self.to_glib_none().0, parent.to_glib_none().0, subject.to_glib_none().0, body.to_glib_none().0, metadata.to_glib_none().0, root.to_glib_none().0, &mut out_commit, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_commit)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_write_commit_detached_metadata")] + pub fn write_commit_detached_metadata<P: IsA<gio::Cancellable>>(&self, checksum: &str, metadata: Option<&glib::Variant>, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_write_commit_detached_metadata(self.to_glib_none().0, checksum.to_glib_none().0, metadata.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_write_commit_with_time")] + pub fn write_commit_with_time<P: IsA<gio::Cancellable>>(&self, parent: Option<&str>, subject: Option<&str>, body: Option<&str>, metadata: Option<&glib::Variant>, root: &RepoFile, time: u64, cancellable: Option<&P>) -> Result<glib::GString, glib::Error> { + unsafe { + let mut out_commit = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_write_commit_with_time(self.to_glib_none().0, parent.to_glib_none().0, subject.to_glib_none().0, body.to_glib_none().0, metadata.to_glib_none().0, root.to_glib_none().0, time, &mut out_commit, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_commit)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_write_config")] + pub fn write_config(&self, new_config: &glib::KeyFile) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_write_config(self.to_glib_none().0, new_config.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_write_content_trusted")] + pub fn write_content_trusted<P: IsA<gio::InputStream>, Q: IsA<gio::Cancellable>>(&self, checksum: &str, object_input: &P, length: u64, cancellable: Option<&Q>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_write_content_trusted(self.to_glib_none().0, checksum.to_glib_none().0, object_input.as_ref().to_glib_none().0, length, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_write_dfd_to_mtree")] + pub fn write_dfd_to_mtree<P: IsA<gio::Cancellable>>(&self, dfd: i32, path: &str, mtree: &MutableTree, modifier: Option<&RepoCommitModifier>, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_write_dfd_to_mtree(self.to_glib_none().0, dfd, path.to_glib_none().0, mtree.to_glib_none().0, modifier.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_write_directory_to_mtree")] + pub fn write_directory_to_mtree<P: IsA<gio::File>, Q: IsA<gio::Cancellable>>(&self, dir: &P, mtree: &MutableTree, modifier: Option<&RepoCommitModifier>, cancellable: Option<&Q>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_write_directory_to_mtree(self.to_glib_none().0, dir.as_ref().to_glib_none().0, mtree.to_glib_none().0, modifier.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_write_metadata_stream_trusted")] + pub fn write_metadata_stream_trusted<P: IsA<gio::InputStream>, Q: IsA<gio::Cancellable>>(&self, objtype: ObjectType, checksum: &str, object_input: &P, length: u64, cancellable: Option<&Q>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_write_metadata_stream_trusted(self.to_glib_none().0, objtype.into_glib(), checksum.to_glib_none().0, object_input.as_ref().to_glib_none().0, length, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_write_metadata_trusted")] + pub fn write_metadata_trusted<P: IsA<gio::Cancellable>>(&self, objtype: ObjectType, checksum: &str, variant: &glib::Variant, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_write_metadata_trusted(self.to_glib_none().0, objtype.into_glib(), checksum.to_glib_none().0, variant.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_write_mtree")] + pub fn write_mtree<P: IsA<gio::Cancellable>>(&self, mtree: &MutableTree, cancellable: Option<&P>) -> Result<gio::File, glib::Error> { + unsafe { + let mut out_file = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_write_mtree(self.to_glib_none().0, mtree.to_glib_none().0, &mut out_file, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_file)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2021_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_2")))] + #[doc(alias = "ostree_repo_write_regfile")] + pub fn write_regfile(&self, expected_checksum: Option<&str>, uid: u32, gid: u32, mode: u32, content_len: u64, xattrs: Option<&glib::Variant>) -> Result<ContentWriter, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_repo_write_regfile(self.to_glib_none().0, expected_checksum.to_glib_none().0, uid, gid, mode, content_len, xattrs.to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2021_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_2")))] + #[doc(alias = "ostree_repo_write_regfile_inline")] + pub fn write_regfile_inline<P: IsA<gio::Cancellable>>(&self, expected_checksum: Option<&str>, uid: u32, gid: u32, mode: u32, xattrs: Option<&glib::Variant>, buf: &[u8], cancellable: Option<&P>) -> Result<glib::GString, glib::Error> { + let len = buf.len() as usize; + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_repo_write_regfile_inline(self.to_glib_none().0, expected_checksum.to_glib_none().0, uid, gid, mode, xattrs.to_glib_none().0, buf.to_glib_none().0, len, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2021_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_2")))] + #[doc(alias = "ostree_repo_write_symlink")] + pub fn write_symlink<P: IsA<gio::Cancellable>>(&self, expected_checksum: Option<&str>, uid: u32, gid: u32, xattrs: Option<&glib::Variant>, symlink_target: &str, cancellable: Option<&P>) -> Result<glib::GString, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_repo_write_symlink(self.to_glib_none().0, expected_checksum.to_glib_none().0, uid, gid, xattrs.to_glib_none().0, symlink_target.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "remotes-config-dir")] + pub fn remotes_config_dir(&self) -> Option<glib::GString> { + unsafe { + let mut value = glib::Value::from_type(<glib::GString as StaticType>::static_type()); + glib::gobject_ffi::g_object_get_property(self.as_ptr() as *mut glib::gobject_ffi::GObject, b"remotes-config-dir\0".as_ptr() as *const _, value.to_glib_none_mut().0); + value.get().expect("Return Value for property `remotes-config-dir` getter") + } + } + + #[doc(alias = "sysroot-path")] + pub fn sysroot_path(&self) -> Option<gio::File> { + unsafe { + let mut value = glib::Value::from_type(<gio::File as StaticType>::static_type()); + glib::gobject_ffi::g_object_get_property(self.as_ptr() as *mut glib::gobject_ffi::GObject, b"sysroot-path\0".as_ptr() as *const _, value.to_glib_none_mut().0); + value.get().expect("Return Value for property `sysroot-path` getter") + } + } + + #[cfg(any(feature = "v2017_10", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_10")))] + #[doc(alias = "ostree_repo_create_at")] + pub fn create_at<P: IsA<gio::Cancellable>>(dfd: i32, path: &str, mode: RepoMode, options: Option<&glib::Variant>, cancellable: Option<&P>) -> Result<Repo, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_repo_create_at(dfd, path.to_glib_none().0, mode.into_glib(), options.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_mode_from_string")] + pub fn mode_from_string(mode: &str) -> Result<RepoMode, glib::Error> { + unsafe { + let mut out_mode = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_mode_from_string(mode.to_glib_none().0, out_mode.as_mut_ptr(), &mut error); + let out_mode = out_mode.assume_init(); + if error.is_null() { Ok(from_glib(out_mode)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2017_10", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_10")))] + #[doc(alias = "ostree_repo_open_at")] + pub fn open_at<P: IsA<gio::Cancellable>>(dfd: i32, path: &str, cancellable: Option<&P>) -> Result<Repo, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_repo_open_at(dfd, path.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + //#[doc(alias = "ostree_repo_pull_default_console_progress_changed")] + //pub fn pull_default_console_progress_changed(progress: &AsyncProgress, user_data: /*Unimplemented*/Option<Fundamental: Pointer>) { + // unsafe { TODO: call ffi:ostree_repo_pull_default_console_progress_changed() } + //} + + //#[cfg(any(feature = "v2018_5", feature = "dox"))] + //#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_5")))] + //#[doc(alias = "ostree_repo_traverse_new_parents")] + //pub fn traverse_new_parents() -> /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 2, id: 194 }/TypeId { ns_id: 2, id: 194 } { + // unsafe { TODO: call ffi:ostree_repo_traverse_new_parents() } + //} + + //#[doc(alias = "ostree_repo_traverse_new_reachable")] + //pub fn traverse_new_reachable() -> /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 2, id: 194 }/TypeId { ns_id: 2, id: 194 } { + // unsafe { TODO: call ffi:ostree_repo_traverse_new_reachable() } + //} + + //#[cfg(any(feature = "v2018_5", feature = "dox"))] + //#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_5")))] + //#[doc(alias = "ostree_repo_traverse_parents_get_commits")] + //pub fn traverse_parents_get_commits(parents: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 25 }/TypeId { ns_id: 0, id: 25 }, object: &glib::Variant) -> Vec<glib::GString> { + // unsafe { TODO: call ffi:ostree_repo_traverse_parents_get_commits() } + //} + + #[doc(alias = "gpg-verify-result")] + pub fn connect_gpg_verify_result<F: Fn(&Self, &str, &GpgVerifyResult) + Send + 'static>(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn gpg_verify_result_trampoline<F: Fn(&Repo, &str, &GpgVerifyResult) + Send + 'static>(this: *mut ffi::OstreeRepo, checksum: *mut libc::c_char, result: *mut ffi::OstreeGpgVerifyResult, f: glib::ffi::gpointer) { + let f: &F = &*(f as *const F); + f(&from_glib_borrow(this), &glib::GString::from_glib_borrow(checksum), &from_glib_borrow(result)) + } + unsafe { + let f: Box_<F> = Box_::new(f); + connect_raw(self.as_ptr() as *mut _, b"gpg-verify-result\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>(gpg_verify_result_trampoline::<F> as *const ())), Box_::into_raw(f)) + } + } +} + +unsafe impl Send for Repo {} + +impl fmt::Display for Repo { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("Repo") + } +} diff --git a/rust-bindings/src/auto/repo_commit_modifier.rs b/rust-bindings/src/auto/repo_commit_modifier.rs new file mode 100644 index 0000000000..eea16a82a0 --- /dev/null +++ b/rust-bindings/src/auto/repo_commit_modifier.rs @@ -0,0 +1,107 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use crate::Repo; +use crate::RepoCommitFilterResult; +use crate::RepoCommitModifierFlags; +#[cfg(any(feature = "v2017_13", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_13")))] +use crate::RepoDevInoCache; +use crate::SePolicy; +#[cfg(any(feature = "v2020_4", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_4")))] +use glib::object::IsA; +use glib::translate::*; +use std::boxed::Box as Box_; +#[cfg(any(feature = "v2020_4", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_4")))] +use std::ptr; + +glib::wrapper! { + #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] + pub struct RepoCommitModifier(Shared<ffi::OstreeRepoCommitModifier>); + + match fn { + ref => |ptr| ffi::ostree_repo_commit_modifier_ref(ptr), + unref => |ptr| ffi::ostree_repo_commit_modifier_unref(ptr), + type_ => || ffi::ostree_repo_commit_modifier_get_type(), + } +} + +impl RepoCommitModifier { + #[doc(alias = "ostree_repo_commit_modifier_new")] + pub fn new(flags: RepoCommitModifierFlags, commit_filter: Option<Box_<dyn Fn(&Repo, &str, &gio::FileInfo) -> RepoCommitFilterResult + 'static>>) -> RepoCommitModifier { + let commit_filter_data: Box_<Option<Box_<dyn Fn(&Repo, &str, &gio::FileInfo) -> RepoCommitFilterResult + 'static>>> = Box_::new(commit_filter); + unsafe extern "C" fn commit_filter_func(repo: *mut ffi::OstreeRepo, path: *const libc::c_char, file_info: *mut gio::ffi::GFileInfo, user_data: glib::ffi::gpointer) -> ffi::OstreeRepoCommitFilterResult { + let repo = from_glib_borrow(repo); + let path: Borrowed<glib::GString> = from_glib_borrow(path); + let file_info = from_glib_borrow(file_info); + let callback: &Option<Box_<dyn Fn(&Repo, &str, &gio::FileInfo) -> RepoCommitFilterResult + 'static>> = &*(user_data as *mut _); + let res = if let Some(ref callback) = *callback { + callback(&repo, path.as_str(), &file_info) + } else { + panic!("cannot get closure...") + }; + res.into_glib() + } + let commit_filter = if commit_filter_data.is_some() { Some(commit_filter_func as _) } else { None }; + unsafe extern "C" fn destroy_notify_func(data: glib::ffi::gpointer) { + let _callback: Box_<Option<Box_<dyn Fn(&Repo, &str, &gio::FileInfo) -> RepoCommitFilterResult + 'static>>> = Box_::from_raw(data as *mut _); + } + let destroy_call3 = Some(destroy_notify_func as _); + let super_callback0: Box_<Option<Box_<dyn Fn(&Repo, &str, &gio::FileInfo) -> RepoCommitFilterResult + 'static>>> = commit_filter_data; + unsafe { + from_glib_full(ffi::ostree_repo_commit_modifier_new(flags.into_glib(), commit_filter, Box_::into_raw(super_callback0) as *mut _, destroy_call3)) + } + } + + #[cfg(any(feature = "v2017_13", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_13")))] + #[doc(alias = "ostree_repo_commit_modifier_set_devino_cache")] + pub fn set_devino_cache(&self, cache: &RepoDevInoCache) { + unsafe { + ffi::ostree_repo_commit_modifier_set_devino_cache(self.to_glib_none().0, cache.to_glib_none().0); + } + } + + #[doc(alias = "ostree_repo_commit_modifier_set_sepolicy")] + pub fn set_sepolicy(&self, sepolicy: Option<&SePolicy>) { + unsafe { + ffi::ostree_repo_commit_modifier_set_sepolicy(self.to_glib_none().0, sepolicy.to_glib_none().0); + } + } + + #[cfg(any(feature = "v2020_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_4")))] + #[doc(alias = "ostree_repo_commit_modifier_set_sepolicy_from_commit")] + pub fn set_sepolicy_from_commit<P: IsA<gio::Cancellable>>(&self, repo: &Repo, rev: &str, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_commit_modifier_set_sepolicy_from_commit(self.to_glib_none().0, repo.to_glib_none().0, rev.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_commit_modifier_set_xattr_callback")] + pub fn set_xattr_callback<P: Fn(&Repo, &str, &gio::FileInfo) -> glib::Variant + 'static>(&self, callback: P) { + let callback_data: Box_<P> = Box_::new(callback); + unsafe extern "C" fn callback_func<P: Fn(&Repo, &str, &gio::FileInfo) -> glib::Variant + 'static>(repo: *mut ffi::OstreeRepo, path: *const libc::c_char, file_info: *mut gio::ffi::GFileInfo, user_data: glib::ffi::gpointer) -> *mut glib::ffi::GVariant { + let repo = from_glib_borrow(repo); + let path: Borrowed<glib::GString> = from_glib_borrow(path); + let file_info = from_glib_borrow(file_info); + let callback: &P = &*(user_data as *mut _); + let res = (*callback)(&repo, path.as_str(), &file_info); + res.to_glib_full() + } + let callback = Some(callback_func::<P> as _); + unsafe extern "C" fn destroy_func<P: Fn(&Repo, &str, &gio::FileInfo) -> glib::Variant + 'static>(data: glib::ffi::gpointer) { + let _callback: Box_<P> = Box_::from_raw(data as *mut _); + } + let destroy_call2 = Some(destroy_func::<P> as _); + let super_callback0: Box_<P> = callback_data; + unsafe { + ffi::ostree_repo_commit_modifier_set_xattr_callback(self.to_glib_none().0, callback, destroy_call2, Box_::into_raw(super_callback0) as *mut _); + } + } +} diff --git a/rust-bindings/src/auto/repo_dev_ino_cache.rs b/rust-bindings/src/auto/repo_dev_ino_cache.rs new file mode 100644 index 0000000000..1cc7cd438a --- /dev/null +++ b/rust-bindings/src/auto/repo_dev_ino_cache.rs @@ -0,0 +1,31 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use glib::translate::*; + +glib::wrapper! { + #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] + pub struct RepoDevInoCache(Shared<ffi::OstreeRepoDevInoCache>); + + match fn { + ref => |ptr| ffi::ostree_repo_devino_cache_ref(ptr), + unref => |ptr| ffi::ostree_repo_devino_cache_unref(ptr), + type_ => || ffi::ostree_repo_devino_cache_get_type(), + } +} + +impl RepoDevInoCache { + #[doc(alias = "ostree_repo_devino_cache_new")] + pub fn new() -> RepoDevInoCache { + unsafe { + from_glib_full(ffi::ostree_repo_devino_cache_new()) + } + } +} + +impl Default for RepoDevInoCache { + fn default() -> Self { + Self::new() + } +} diff --git a/rust-bindings/src/auto/repo_file.rs b/rust-bindings/src/auto/repo_file.rs new file mode 100644 index 0000000000..07c17ee754 --- /dev/null +++ b/rust-bindings/src/auto/repo_file.rs @@ -0,0 +1,127 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use crate::Repo; +use glib::object::IsA; +use glib::translate::*; +use std::fmt; +use std::mem; +use std::ptr; + +glib::wrapper! { + #[doc(alias = "OstreeRepoFile")] + pub struct RepoFile(Object<ffi::OstreeRepoFile, ffi::OstreeRepoFileClass>) @implements gio::File; + + match fn { + type_ => || ffi::ostree_repo_file_get_type(), + } +} + +impl RepoFile { + #[doc(alias = "ostree_repo_file_ensure_resolved")] + pub fn ensure_resolved(&self) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_file_ensure_resolved(self.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_file_get_checksum")] + #[doc(alias = "get_checksum")] + pub fn checksum(&self) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_repo_file_get_checksum(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_repo_file_get_repo")] + #[doc(alias = "get_repo")] + pub fn repo(&self) -> Option<Repo> { + unsafe { + from_glib_none(ffi::ostree_repo_file_get_repo(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_repo_file_get_root")] + #[doc(alias = "get_root")] + pub fn root(&self) -> Option<RepoFile> { + unsafe { + from_glib_none(ffi::ostree_repo_file_get_root(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_repo_file_get_xattrs")] + #[doc(alias = "get_xattrs")] + pub fn xattrs<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<glib::Variant, glib::Error> { + unsafe { + let mut out_xattrs = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_file_get_xattrs(self.to_glib_none().0, &mut out_xattrs, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_xattrs)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_file_tree_find_child")] + pub fn tree_find_child(&self, name: &str) -> (i32, bool, glib::Variant) { + unsafe { + let mut is_dir = mem::MaybeUninit::uninit(); + let mut out_container = ptr::null_mut(); + let ret = ffi::ostree_repo_file_tree_find_child(self.to_glib_none().0, name.to_glib_none().0, is_dir.as_mut_ptr(), &mut out_container); + let is_dir = is_dir.assume_init(); + (ret, from_glib(is_dir), from_glib_full(out_container)) + } + } + + #[doc(alias = "ostree_repo_file_tree_get_contents")] + pub fn tree_get_contents(&self) -> Option<glib::Variant> { + unsafe { + from_glib_full(ffi::ostree_repo_file_tree_get_contents(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_repo_file_tree_get_contents_checksum")] + pub fn tree_get_contents_checksum(&self) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_repo_file_tree_get_contents_checksum(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_repo_file_tree_get_metadata")] + pub fn tree_get_metadata(&self) -> Option<glib::Variant> { + unsafe { + from_glib_full(ffi::ostree_repo_file_tree_get_metadata(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_repo_file_tree_get_metadata_checksum")] + pub fn tree_get_metadata_checksum(&self) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_repo_file_tree_get_metadata_checksum(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_repo_file_tree_query_child")] + pub fn tree_query_child<P: IsA<gio::Cancellable>>(&self, n: i32, attributes: &str, flags: gio::FileQueryInfoFlags, cancellable: Option<&P>) -> Result<gio::FileInfo, glib::Error> { + unsafe { + let mut out_info = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_file_tree_query_child(self.to_glib_none().0, n, attributes.to_glib_none().0, flags.into_glib(), &mut out_info, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_info)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_file_tree_set_metadata")] + pub fn tree_set_metadata(&self, checksum: &str, metadata: &glib::Variant) { + unsafe { + ffi::ostree_repo_file_tree_set_metadata(self.to_glib_none().0, checksum.to_glib_none().0, metadata.to_glib_none().0); + } + } +} + +impl fmt::Display for RepoFile { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("RepoFile") + } +} diff --git a/rust-bindings/src/auto/repo_finder.rs b/rust-bindings/src/auto/repo_finder.rs new file mode 100644 index 0000000000..ed5e1f86fe --- /dev/null +++ b/rust-bindings/src/auto/repo_finder.rs @@ -0,0 +1,32 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use crate::RepoFinderResult; +use glib::object::IsA; +use glib::translate::*; +use std::fmt; +use std::ptr; + +glib::wrapper! { + #[doc(alias = "OstreeRepoFinder")] + pub struct RepoFinder(Interface<ffi::OstreeRepoFinder, ffi::OstreeRepoFinderInterface>); + + match fn { + type_ => || ffi::ostree_repo_finder_get_type(), + } +} + +impl RepoFinder {} + +pub const NONE_REPO_FINDER: Option<&RepoFinder> = None; + +pub trait RepoFinderExt: 'static {} + +impl<O: IsA<RepoFinder>> RepoFinderExt for O {} + +impl fmt::Display for RepoFinder { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("RepoFinder") + } +} diff --git a/rust-bindings/src/auto/repo_finder_avahi.rs b/rust-bindings/src/auto/repo_finder_avahi.rs new file mode 100644 index 0000000000..8910a43781 --- /dev/null +++ b/rust-bindings/src/auto/repo_finder_avahi.rs @@ -0,0 +1,48 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use crate::RepoFinder; +use glib::translate::*; +use std::fmt; +use std::ptr; + +glib::wrapper! { + #[doc(alias = "OstreeRepoFinderAvahi")] + pub struct RepoFinderAvahi(Object<ffi::OstreeRepoFinderAvahi, ffi::OstreeRepoFinderAvahiClass>) @implements RepoFinder; + + match fn { + type_ => || ffi::ostree_repo_finder_avahi_get_type(), + } +} + +impl RepoFinderAvahi { + #[doc(alias = "ostree_repo_finder_avahi_new")] + pub fn new(context: Option<&glib::MainContext>) -> RepoFinderAvahi { + unsafe { + from_glib_full(ffi::ostree_repo_finder_avahi_new(context.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_repo_finder_avahi_start")] + pub fn start(&self) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_repo_finder_avahi_start(self.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_repo_finder_avahi_stop")] + pub fn stop(&self) { + unsafe { + ffi::ostree_repo_finder_avahi_stop(self.to_glib_none().0); + } + } +} + +impl fmt::Display for RepoFinderAvahi { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("RepoFinderAvahi") + } +} diff --git a/rust-bindings/src/auto/repo_finder_config.rs b/rust-bindings/src/auto/repo_finder_config.rs new file mode 100644 index 0000000000..2b76d99be3 --- /dev/null +++ b/rust-bindings/src/auto/repo_finder_config.rs @@ -0,0 +1,39 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use crate::RepoFinder; +use glib::translate::*; +use std::fmt; + +glib::wrapper! { + #[doc(alias = "OstreeRepoFinderConfig")] + pub struct RepoFinderConfig(Object<ffi::OstreeRepoFinderConfig, ffi::OstreeRepoFinderConfigClass>) @implements RepoFinder; + + match fn { + type_ => || ffi::ostree_repo_finder_config_get_type(), + } +} + +impl RepoFinderConfig { + #[doc(alias = "ostree_repo_finder_config_new")] + pub fn new() -> RepoFinderConfig { + unsafe { + from_glib_full(ffi::ostree_repo_finder_config_new()) + } + } +} + +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +impl Default for RepoFinderConfig { + fn default() -> Self { + Self::new() + } +} + +impl fmt::Display for RepoFinderConfig { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("RepoFinderConfig") + } +} diff --git a/rust-bindings/src/auto/repo_finder_mount.rs b/rust-bindings/src/auto/repo_finder_mount.rs new file mode 100644 index 0000000000..eda91f3850 --- /dev/null +++ b/rust-bindings/src/auto/repo_finder_mount.rs @@ -0,0 +1,44 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use crate::RepoFinder; +use glib::object::IsA; +use glib::object::ObjectType as ObjectType_; +use glib::translate::*; +use glib::StaticType; +use std::fmt; + +glib::wrapper! { + #[doc(alias = "OstreeRepoFinderMount")] + pub struct RepoFinderMount(Object<ffi::OstreeRepoFinderMount, ffi::OstreeRepoFinderMountClass>) @implements RepoFinder; + + match fn { + type_ => || ffi::ostree_repo_finder_mount_get_type(), + } +} + +impl RepoFinderMount { + #[doc(alias = "ostree_repo_finder_mount_new")] + pub fn new<P: IsA<gio::VolumeMonitor>>(monitor: Option<&P>) -> RepoFinderMount { + unsafe { + from_glib_full(ffi::ostree_repo_finder_mount_new(monitor.map(|p| p.as_ref()).to_glib_none().0)) + } + } + + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn monitor(&self) -> Option<gio::VolumeMonitor> { + unsafe { + let mut value = glib::Value::from_type(<gio::VolumeMonitor as StaticType>::static_type()); + glib::gobject_ffi::g_object_get_property(self.as_ptr() as *mut glib::gobject_ffi::GObject, b"monitor\0".as_ptr() as *const _, value.to_glib_none_mut().0); + value.get().expect("Return Value for property `monitor` getter") + } + } +} + +impl fmt::Display for RepoFinderMount { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("RepoFinderMount") + } +} diff --git a/rust-bindings/src/auto/repo_finder_override.rs b/rust-bindings/src/auto/repo_finder_override.rs new file mode 100644 index 0000000000..d504c180da --- /dev/null +++ b/rust-bindings/src/auto/repo_finder_override.rs @@ -0,0 +1,46 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use crate::RepoFinder; +use glib::translate::*; +use std::fmt; + +glib::wrapper! { + #[doc(alias = "OstreeRepoFinderOverride")] + pub struct RepoFinderOverride(Object<ffi::OstreeRepoFinderOverride, ffi::OstreeRepoFinderOverrideClass>) @implements RepoFinder; + + match fn { + type_ => || ffi::ostree_repo_finder_override_get_type(), + } +} + +impl RepoFinderOverride { + #[doc(alias = "ostree_repo_finder_override_new")] + pub fn new() -> RepoFinderOverride { + unsafe { + from_glib_full(ffi::ostree_repo_finder_override_new()) + } + } + + #[doc(alias = "ostree_repo_finder_override_add_uri")] + pub fn add_uri(&self, uri: &str) { + unsafe { + ffi::ostree_repo_finder_override_add_uri(self.to_glib_none().0, uri.to_glib_none().0); + } + } +} + +#[cfg(any(feature = "v2018_6", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] +impl Default for RepoFinderOverride { + fn default() -> Self { + Self::new() + } +} + +impl fmt::Display for RepoFinderOverride { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("RepoFinderOverride") + } +} diff --git a/rust-bindings/src/auto/repo_finder_result.rs b/rust-bindings/src/auto/repo_finder_result.rs new file mode 100644 index 0000000000..702ec52c92 --- /dev/null +++ b/rust-bindings/src/auto/repo_finder_result.rs @@ -0,0 +1,54 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use std::cmp; +use glib::translate::*; + +glib::wrapper! { + #[derive(Debug, Hash)] + pub struct RepoFinderResult(Boxed<ffi::OstreeRepoFinderResult>); + + match fn { + copy => |ptr| glib::gobject_ffi::g_boxed_copy(ffi::ostree_repo_finder_result_get_type(), ptr as *mut _) as *mut ffi::OstreeRepoFinderResult, + free => |ptr| glib::gobject_ffi::g_boxed_free(ffi::ostree_repo_finder_result_get_type(), ptr as *mut _), + type_ => || ffi::ostree_repo_finder_result_get_type(), + } +} + +impl RepoFinderResult { + //#[doc(alias = "ostree_repo_finder_result_new")] + //pub fn new<P: IsA<RepoFinder>>(remote: &Remote, finder: &P, priority: i32, ref_to_checksum: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 1, id: 0 }/TypeId { ns_id: 0, id: 28 }, ref_to_timestamp: /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 1, id: 0 }/TypeId { ns_id: 0, id: 9 }, summary_last_modified: u64) -> RepoFinderResult { + // unsafe { TODO: call ffi:ostree_repo_finder_result_new() } + //} + + #[doc(alias = "ostree_repo_finder_result_compare")] + fn compare(&self, b: &RepoFinderResult) -> i32 { + unsafe { + ffi::ostree_repo_finder_result_compare(self.to_glib_none().0, b.to_glib_none().0) + } + } +} + +impl PartialEq for RepoFinderResult { + #[inline] + fn eq(&self, other: &Self) -> bool { + self.compare(other) == 0 + } +} + +impl Eq for RepoFinderResult {} + +impl PartialOrd for RepoFinderResult { + #[inline] + fn partial_cmp(&self, other: &Self) -> Option<cmp::Ordering> { + self.compare(other).partial_cmp(&0) + } +} + +impl Ord for RepoFinderResult { + #[inline] + fn cmp(&self, other: &Self) -> cmp::Ordering { + self.compare(other).cmp(&0) + } +} diff --git a/rust-bindings/src/auto/se_policy.rs b/rust-bindings/src/auto/se_policy.rs new file mode 100644 index 0000000000..91148ac79e --- /dev/null +++ b/rust-bindings/src/auto/se_policy.rs @@ -0,0 +1,126 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use crate::Repo; +use crate::SePolicyRestoreconFlags; +use glib::object::IsA; +use glib::object::ObjectType as ObjectType_; +use glib::translate::*; +use glib::StaticType; +use std::fmt; +use std::ptr; + +glib::wrapper! { + #[doc(alias = "OstreeSePolicy")] + pub struct SePolicy(Object<ffi::OstreeSePolicy>); + + match fn { + type_ => || ffi::ostree_sepolicy_get_type(), + } +} + +impl SePolicy { + #[doc(alias = "ostree_sepolicy_new")] + pub fn new<P: IsA<gio::File>, Q: IsA<gio::Cancellable>>(path: &P, cancellable: Option<&Q>) -> Result<SePolicy, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_sepolicy_new(path.as_ref().to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2017_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_4")))] + #[doc(alias = "ostree_sepolicy_new_at")] + pub fn new_at<P: IsA<gio::Cancellable>>(rootfs_dfd: i32, cancellable: Option<&P>) -> Result<SePolicy, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_sepolicy_new_at(rootfs_dfd, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sepolicy_new_from_commit")] + #[doc(alias = "new_from_commit")] + pub fn from_commit<P: IsA<gio::Cancellable>>(repo: &Repo, rev: &str, cancellable: Option<&P>) -> Result<SePolicy, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_sepolicy_new_from_commit(repo.to_glib_none().0, rev.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2016_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_5")))] + #[doc(alias = "ostree_sepolicy_get_csum")] + #[doc(alias = "get_csum")] + pub fn csum(&self) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_sepolicy_get_csum(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_sepolicy_get_label")] + #[doc(alias = "get_label")] + pub fn label<P: IsA<gio::Cancellable>>(&self, relpath: &str, unix_mode: u32, cancellable: Option<&P>) -> Result<glib::GString, glib::Error> { + unsafe { + let mut out_label = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sepolicy_get_label(self.to_glib_none().0, relpath.to_glib_none().0, unix_mode, &mut out_label, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_label)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sepolicy_get_name")] + #[doc(alias = "get_name")] + pub fn name(&self) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_sepolicy_get_name(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_sepolicy_get_path")] + #[doc(alias = "get_path")] + pub fn path(&self) -> Option<gio::File> { + unsafe { + from_glib_none(ffi::ostree_sepolicy_get_path(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_sepolicy_restorecon")] + pub fn restorecon<P: IsA<gio::File>, Q: IsA<gio::Cancellable>>(&self, path: &str, info: Option<&gio::FileInfo>, target: &P, flags: SePolicyRestoreconFlags, cancellable: Option<&Q>) -> Result<glib::GString, glib::Error> { + unsafe { + let mut out_new_label = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sepolicy_restorecon(self.to_glib_none().0, path.to_glib_none().0, info.to_glib_none().0, target.as_ref().to_glib_none().0, flags.into_glib(), &mut out_new_label, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_new_label)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sepolicy_setfscreatecon")] + pub fn setfscreatecon(&self, path: &str, mode: u32) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sepolicy_setfscreatecon(self.to_glib_none().0, path.to_glib_none().0, mode, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "rootfs-dfd")] + pub fn rootfs_dfd(&self) -> i32 { + unsafe { + let mut value = glib::Value::from_type(<i32 as StaticType>::static_type()); + glib::gobject_ffi::g_object_get_property(self.as_ptr() as *mut glib::gobject_ffi::GObject, b"rootfs-dfd\0".as_ptr() as *const _, value.to_glib_none_mut().0); + value.get().expect("Return Value for property `rootfs-dfd` getter") + } + } +} + +unsafe impl Send for SePolicy {} + +impl fmt::Display for SePolicy { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("SePolicy") + } +} diff --git a/rust-bindings/src/auto/sign.rs b/rust-bindings/src/auto/sign.rs new file mode 100644 index 0000000000..7a449245e0 --- /dev/null +++ b/rust-bindings/src/auto/sign.rs @@ -0,0 +1,191 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use crate::Repo; +use glib::object::IsA; +use glib::translate::*; +use std::fmt; +use std::ptr; + +glib::wrapper! { + #[doc(alias = "OstreeSign")] + pub struct Sign(Interface<ffi::OstreeSign, ffi::OstreeSignInterface>); + + match fn { + type_ => || ffi::ostree_sign_get_type(), + } +} + +impl Sign { + #[doc(alias = "ostree_sign_get_all")] + #[doc(alias = "get_all")] + pub fn all() -> Vec<Sign> { + unsafe { + FromGlibPtrContainer::from_glib_full(ffi::ostree_sign_get_all()) + } + } + + #[doc(alias = "ostree_sign_get_by_name")] + #[doc(alias = "get_by_name")] + pub fn by_name(name: &str) -> Result<Sign, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_sign_get_by_name(name.to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } +} + +pub const NONE_SIGN: Option<&Sign> = None; + +pub trait SignExt: 'static { + #[doc(alias = "ostree_sign_add_pk")] + fn add_pk(&self, public_key: &glib::Variant) -> Result<(), glib::Error>; + + #[doc(alias = "ostree_sign_clear_keys")] + fn clear_keys(&self) -> Result<(), glib::Error>; + + #[doc(alias = "ostree_sign_commit")] + fn commit<P: IsA<gio::Cancellable>>(&self, repo: &Repo, commit_checksum: &str, cancellable: Option<&P>) -> Result<(), glib::Error>; + + #[doc(alias = "ostree_sign_commit_verify")] + fn commit_verify<P: IsA<gio::Cancellable>>(&self, repo: &Repo, commit_checksum: &str, cancellable: Option<&P>) -> Result<Option<glib::GString>, glib::Error>; + + #[doc(alias = "ostree_sign_data")] + fn data<P: IsA<gio::Cancellable>>(&self, data: &glib::Bytes, cancellable: Option<&P>) -> Result<glib::Bytes, glib::Error>; + + #[doc(alias = "ostree_sign_data_verify")] + fn data_verify(&self, data: &glib::Bytes, signatures: &glib::Variant) -> Result<Option<glib::GString>, glib::Error>; + + #[doc(alias = "ostree_sign_get_name")] + #[doc(alias = "get_name")] + fn name(&self) -> Option<glib::GString>; + + #[doc(alias = "ostree_sign_load_pk")] + fn load_pk(&self, options: &glib::Variant) -> Result<(), glib::Error>; + + #[doc(alias = "ostree_sign_metadata_format")] + fn metadata_format(&self) -> Option<glib::GString>; + + #[doc(alias = "ostree_sign_metadata_key")] + fn metadata_key(&self) -> Option<glib::GString>; + + #[doc(alias = "ostree_sign_set_pk")] + fn set_pk(&self, public_key: &glib::Variant) -> Result<(), glib::Error>; + + #[doc(alias = "ostree_sign_set_sk")] + fn set_sk(&self, secret_key: &glib::Variant) -> Result<(), glib::Error>; + + #[doc(alias = "ostree_sign_summary")] + fn summary<P: IsA<gio::Cancellable>>(&self, repo: &Repo, keys: &glib::Variant, cancellable: Option<&P>) -> Result<(), glib::Error>; +} + +impl<O: IsA<Sign>> SignExt for O { + fn add_pk(&self, public_key: &glib::Variant) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sign_add_pk(self.as_ref().to_glib_none().0, public_key.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + fn clear_keys(&self) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sign_clear_keys(self.as_ref().to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + fn commit<P: IsA<gio::Cancellable>>(&self, repo: &Repo, commit_checksum: &str, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sign_commit(self.as_ref().to_glib_none().0, repo.to_glib_none().0, commit_checksum.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + fn commit_verify<P: IsA<gio::Cancellable>>(&self, repo: &Repo, commit_checksum: &str, cancellable: Option<&P>) -> Result<Option<glib::GString>, glib::Error> { + unsafe { + let mut out_success_message = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sign_commit_verify(self.as_ref().to_glib_none().0, repo.to_glib_none().0, commit_checksum.to_glib_none().0, &mut out_success_message, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_success_message)) } else { Err(from_glib_full(error)) } + } + } + + fn data<P: IsA<gio::Cancellable>>(&self, data: &glib::Bytes, cancellable: Option<&P>) -> Result<glib::Bytes, glib::Error> { + unsafe { + let mut signature = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sign_data(self.as_ref().to_glib_none().0, data.to_glib_none().0, &mut signature, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(signature)) } else { Err(from_glib_full(error)) } + } + } + + fn data_verify(&self, data: &glib::Bytes, signatures: &glib::Variant) -> Result<Option<glib::GString>, glib::Error> { + unsafe { + let mut out_success_message = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sign_data_verify(self.as_ref().to_glib_none().0, data.to_glib_none().0, signatures.to_glib_none().0, &mut out_success_message, &mut error); + if error.is_null() { Ok(from_glib_full(out_success_message)) } else { Err(from_glib_full(error)) } + } + } + + fn name(&self) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_sign_get_name(self.as_ref().to_glib_none().0)) + } + } + + fn load_pk(&self, options: &glib::Variant) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sign_load_pk(self.as_ref().to_glib_none().0, options.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + fn metadata_format(&self) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_sign_metadata_format(self.as_ref().to_glib_none().0)) + } + } + + fn metadata_key(&self) -> Option<glib::GString> { + unsafe { + from_glib_none(ffi::ostree_sign_metadata_key(self.as_ref().to_glib_none().0)) + } + } + + fn set_pk(&self, public_key: &glib::Variant) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sign_set_pk(self.as_ref().to_glib_none().0, public_key.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + fn set_sk(&self, secret_key: &glib::Variant) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sign_set_sk(self.as_ref().to_glib_none().0, secret_key.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + fn summary<P: IsA<gio::Cancellable>>(&self, repo: &Repo, keys: &glib::Variant, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sign_summary(self.as_ref().to_glib_none().0, repo.to_glib_none().0, keys.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } +} + +impl fmt::Display for Sign { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("Sign") + } +} diff --git a/rust-bindings/src/auto/sysroot.rs b/rust-bindings/src/auto/sysroot.rs new file mode 100644 index 0000000000..f10f630cdf --- /dev/null +++ b/rust-bindings/src/auto/sysroot.rs @@ -0,0 +1,509 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use crate::Deployment; +#[cfg(any(feature = "v2016_4", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] +use crate::DeploymentUnlockedState; +#[cfg(any(feature = "v2017_7", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_7")))] +use crate::Repo; +#[cfg(any(feature = "v2020_7", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_7")))] +use crate::SysrootDeployTreeOpts; +use crate::SysrootSimpleWriteDeploymentFlags; +#[cfg(any(feature = "v2017_4", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_4")))] +use crate::SysrootWriteDeploymentsOpts; +use glib::object::IsA; +#[cfg(any(feature = "v2017_10", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_10")))] +use glib::object::ObjectType as ObjectType_; +#[cfg(any(feature = "v2017_10", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_10")))] +use glib::signal::connect_raw; +#[cfg(any(feature = "v2017_10", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_10")))] +use glib::signal::SignalHandlerId; +use glib::translate::*; +use std::boxed::Box as Box_; +use std::fmt; +use std::mem; +#[cfg(any(feature = "v2017_10", feature = "dox"))] +#[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_10")))] +use std::mem::transmute; +use std::pin::Pin; +use std::ptr; + +glib::wrapper! { + #[doc(alias = "OstreeSysroot")] + pub struct Sysroot(Object<ffi::OstreeSysroot>); + + match fn { + type_ => || ffi::ostree_sysroot_get_type(), + } +} + +impl Sysroot { + #[doc(alias = "ostree_sysroot_new")] + pub fn new<P: IsA<gio::File>>(path: Option<&P>) -> Sysroot { + unsafe { + from_glib_full(ffi::ostree_sysroot_new(path.map(|p| p.as_ref()).to_glib_none().0)) + } + } + + #[doc(alias = "ostree_sysroot_new_default")] + pub fn new_default() -> Sysroot { + unsafe { + from_glib_full(ffi::ostree_sysroot_new_default()) + } + } + + #[doc(alias = "ostree_sysroot_cleanup")] + pub fn cleanup<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_cleanup(self.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + //#[cfg(any(feature = "v2018_6", feature = "dox"))] + //#[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + //#[doc(alias = "ostree_sysroot_cleanup_prune_repo")] + //pub fn cleanup_prune_repo<P: IsA<gio::Cancellable>>(&self, options: /*Ignored*/&mut RepoPruneOptions, cancellable: Option<&P>) -> Result<(i32, i32, u64), glib::Error> { + // unsafe { TODO: call ffi:ostree_sysroot_cleanup_prune_repo() } + //} + + #[cfg(any(feature = "v2018_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_5")))] + #[doc(alias = "ostree_sysroot_deploy_tree")] + pub fn deploy_tree<P: IsA<gio::Cancellable>>(&self, osname: Option<&str>, revision: &str, origin: Option<&glib::KeyFile>, provided_merge_deployment: Option<&Deployment>, override_kernel_argv: &[&str], cancellable: Option<&P>) -> Result<Deployment, glib::Error> { + unsafe { + let mut out_new_deployment = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_deploy_tree(self.to_glib_none().0, osname.to_glib_none().0, revision.to_glib_none().0, origin.to_glib_none().0, provided_merge_deployment.to_glib_none().0, override_kernel_argv.to_glib_none().0, &mut out_new_deployment, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_new_deployment)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2020_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_7")))] + #[doc(alias = "ostree_sysroot_deploy_tree_with_options")] + pub fn deploy_tree_with_options<P: IsA<gio::Cancellable>>(&self, osname: Option<&str>, revision: &str, origin: Option<&glib::KeyFile>, provided_merge_deployment: Option<&Deployment>, opts: Option<&SysrootDeployTreeOpts>, cancellable: Option<&P>) -> Result<Deployment, glib::Error> { + unsafe { + let mut out_new_deployment = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_deploy_tree_with_options(self.to_glib_none().0, osname.to_glib_none().0, revision.to_glib_none().0, origin.to_glib_none().0, provided_merge_deployment.to_glib_none().0, mut_override(opts.to_glib_none().0), &mut out_new_deployment, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_new_deployment)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sysroot_deployment_set_kargs")] + pub fn deployment_set_kargs<P: IsA<gio::Cancellable>>(&self, deployment: &Deployment, new_kargs: &[&str], cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_deployment_set_kargs(self.to_glib_none().0, deployment.to_glib_none().0, new_kargs.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sysroot_deployment_set_mutable")] + pub fn deployment_set_mutable<P: IsA<gio::Cancellable>>(&self, deployment: &Deployment, is_mutable: bool, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_deployment_set_mutable(self.to_glib_none().0, deployment.to_glib_none().0, is_mutable.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2018_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_3")))] + #[doc(alias = "ostree_sysroot_deployment_set_pinned")] + pub fn deployment_set_pinned(&self, deployment: &Deployment, is_pinned: bool) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_deployment_set_pinned(self.to_glib_none().0, deployment.to_glib_none().0, is_pinned.into_glib(), &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2016_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] + #[doc(alias = "ostree_sysroot_deployment_unlock")] + pub fn deployment_unlock<P: IsA<gio::Cancellable>>(&self, deployment: &Deployment, unlocked_state: DeploymentUnlockedState, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_deployment_unlock(self.to_glib_none().0, deployment.to_glib_none().0, unlocked_state.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sysroot_ensure_initialized")] + pub fn ensure_initialized<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_ensure_initialized(self.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sysroot_get_booted_deployment")] + #[doc(alias = "get_booted_deployment")] + pub fn booted_deployment(&self) -> Option<Deployment> { + unsafe { + from_glib_none(ffi::ostree_sysroot_get_booted_deployment(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_sysroot_get_bootversion")] + #[doc(alias = "get_bootversion")] + pub fn bootversion(&self) -> i32 { + unsafe { + ffi::ostree_sysroot_get_bootversion(self.to_glib_none().0) + } + } + + #[doc(alias = "ostree_sysroot_get_deployment_directory")] + #[doc(alias = "get_deployment_directory")] + pub fn deployment_directory(&self, deployment: &Deployment) -> Option<gio::File> { + unsafe { + from_glib_full(ffi::ostree_sysroot_get_deployment_directory(self.to_glib_none().0, deployment.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_sysroot_get_deployment_dirpath")] + #[doc(alias = "get_deployment_dirpath")] + pub fn deployment_dirpath(&self, deployment: &Deployment) -> Option<glib::GString> { + unsafe { + from_glib_full(ffi::ostree_sysroot_get_deployment_dirpath(self.to_glib_none().0, deployment.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_sysroot_get_deployments")] + #[doc(alias = "get_deployments")] + pub fn deployments(&self) -> Vec<Deployment> { + unsafe { + FromGlibPtrContainer::from_glib_container(ffi::ostree_sysroot_get_deployments(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_sysroot_get_fd")] + #[doc(alias = "get_fd")] + pub fn fd(&self) -> i32 { + unsafe { + ffi::ostree_sysroot_get_fd(self.to_glib_none().0) + } + } + + #[doc(alias = "ostree_sysroot_get_merge_deployment")] + #[doc(alias = "get_merge_deployment")] + pub fn merge_deployment(&self, osname: Option<&str>) -> Option<Deployment> { + unsafe { + from_glib_full(ffi::ostree_sysroot_get_merge_deployment(self.to_glib_none().0, osname.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_sysroot_get_path")] + #[doc(alias = "get_path")] + pub fn path(&self) -> Option<gio::File> { + unsafe { + from_glib_none(ffi::ostree_sysroot_get_path(self.to_glib_none().0)) + } + } + + #[cfg(any(feature = "v2018_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_5")))] + #[doc(alias = "ostree_sysroot_get_staged_deployment")] + #[doc(alias = "get_staged_deployment")] + pub fn staged_deployment(&self) -> Option<Deployment> { + unsafe { + from_glib_none(ffi::ostree_sysroot_get_staged_deployment(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_sysroot_get_subbootversion")] + #[doc(alias = "get_subbootversion")] + pub fn subbootversion(&self) -> i32 { + unsafe { + ffi::ostree_sysroot_get_subbootversion(self.to_glib_none().0) + } + } + + #[cfg(any(feature = "v2016_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] + #[doc(alias = "ostree_sysroot_init_osname")] + pub fn init_osname<P: IsA<gio::Cancellable>>(&self, osname: &str, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_init_osname(self.to_glib_none().0, osname.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2020_1", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_1")))] + #[doc(alias = "ostree_sysroot_initialize")] + pub fn initialize(&self) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_initialize(self.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2020_1", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_1")))] + #[doc(alias = "ostree_sysroot_is_booted")] + pub fn is_booted(&self) -> bool { + unsafe { + from_glib(ffi::ostree_sysroot_is_booted(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_sysroot_load")] + pub fn load<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_load(self.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2016_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] + #[doc(alias = "ostree_sysroot_load_if_changed")] + pub fn load_if_changed<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<bool, glib::Error> { + unsafe { + let mut out_changed = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_load_if_changed(self.to_glib_none().0, out_changed.as_mut_ptr(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + let out_changed = out_changed.assume_init(); + if error.is_null() { Ok(from_glib(out_changed)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sysroot_lock")] + pub fn lock(&self) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_lock(self.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sysroot_lock_async")] + pub fn lock_async<P: IsA<gio::Cancellable>, Q: FnOnce(Result<(), glib::Error>) + Send + 'static>(&self, cancellable: Option<&P>, callback: Q) { + let user_data: Box_<Q> = Box_::new(callback); + unsafe extern "C" fn lock_async_trampoline<Q: FnOnce(Result<(), glib::Error>) + Send + 'static>(_source_object: *mut glib::gobject_ffi::GObject, res: *mut gio::ffi::GAsyncResult, user_data: glib::ffi::gpointer) { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_lock_finish(_source_object as *mut _, res, &mut error); + let result = if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) }; + let callback: Box_<Q> = Box_::from_raw(user_data as *mut _); + callback(result); + } + let callback = lock_async_trampoline::<Q>; + unsafe { + ffi::ostree_sysroot_lock_async(self.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, Some(callback), Box_::into_raw(user_data) as *mut _); + } + } + + + pub fn lock_async_future(&self) -> Pin<Box_<dyn std::future::Future<Output = Result<(), glib::Error>> + 'static>> { + + Box_::pin(gio::GioFuture::new(self, move |obj, cancellable, send| { + obj.lock_async( + Some(cancellable), + move |res| { + send.resolve(res); + }, + ); + })) + } + + #[doc(alias = "ostree_sysroot_origin_new_from_refspec")] + pub fn origin_new_from_refspec(&self, refspec: &str) -> Option<glib::KeyFile> { + unsafe { + from_glib_full(ffi::ostree_sysroot_origin_new_from_refspec(self.to_glib_none().0, refspec.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_sysroot_prepare_cleanup")] + pub fn prepare_cleanup<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_prepare_cleanup(self.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2017_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_7")))] + #[doc(alias = "ostree_sysroot_query_deployments_for")] + pub fn query_deployments_for(&self, osname: Option<&str>) -> (Option<Deployment>, Option<Deployment>) { + unsafe { + let mut out_pending = ptr::null_mut(); + let mut out_rollback = ptr::null_mut(); + ffi::ostree_sysroot_query_deployments_for(self.to_glib_none().0, osname.to_glib_none().0, &mut out_pending, &mut out_rollback); + (from_glib_full(out_pending), from_glib_full(out_rollback)) + } + } + + #[cfg(any(feature = "v2017_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_7")))] + #[doc(alias = "ostree_sysroot_repo")] + pub fn repo(&self) -> Option<Repo> { + unsafe { + from_glib_none(ffi::ostree_sysroot_repo(self.to_glib_none().0)) + } + } + + #[cfg(any(feature = "v2021_1", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_1")))] + #[doc(alias = "ostree_sysroot_require_booted_deployment")] + pub fn require_booted_deployment(&self) -> Result<Deployment, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_sysroot_require_booted_deployment(self.to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_none(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2020_1", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_1")))] + #[doc(alias = "ostree_sysroot_set_mount_namespace_in_use")] + pub fn set_mount_namespace_in_use(&self) { + unsafe { + ffi::ostree_sysroot_set_mount_namespace_in_use(self.to_glib_none().0); + } + } + + #[doc(alias = "ostree_sysroot_simple_write_deployment")] + pub fn simple_write_deployment<P: IsA<gio::Cancellable>>(&self, osname: Option<&str>, new_deployment: &Deployment, merge_deployment: Option<&Deployment>, flags: SysrootSimpleWriteDeploymentFlags, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_simple_write_deployment(self.to_glib_none().0, osname.to_glib_none().0, new_deployment.to_glib_none().0, merge_deployment.to_glib_none().0, flags.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2020_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_7")))] + #[doc(alias = "ostree_sysroot_stage_overlay_initrd")] + pub fn stage_overlay_initrd<P: IsA<gio::Cancellable>>(&self, fd: i32, cancellable: Option<&P>) -> Result<glib::GString, glib::Error> { + unsafe { + let mut out_checksum = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_stage_overlay_initrd(self.to_glib_none().0, fd, &mut out_checksum, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_checksum)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2018_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_5")))] + #[doc(alias = "ostree_sysroot_stage_tree")] + pub fn stage_tree<P: IsA<gio::Cancellable>>(&self, osname: Option<&str>, revision: &str, origin: Option<&glib::KeyFile>, merge_deployment: Option<&Deployment>, override_kernel_argv: &[&str], cancellable: Option<&P>) -> Result<Deployment, glib::Error> { + unsafe { + let mut out_new_deployment = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_stage_tree(self.to_glib_none().0, osname.to_glib_none().0, revision.to_glib_none().0, origin.to_glib_none().0, merge_deployment.to_glib_none().0, override_kernel_argv.to_glib_none().0, &mut out_new_deployment, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_new_deployment)) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2020_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_7")))] + #[doc(alias = "ostree_sysroot_stage_tree_with_options")] + pub fn stage_tree_with_options<P: IsA<gio::Cancellable>>(&self, osname: Option<&str>, revision: &str, origin: Option<&glib::KeyFile>, merge_deployment: Option<&Deployment>, opts: &SysrootDeployTreeOpts, cancellable: Option<&P>) -> Result<Deployment, glib::Error> { + unsafe { + let mut out_new_deployment = ptr::null_mut(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_stage_tree_with_options(self.to_glib_none().0, osname.to_glib_none().0, revision.to_glib_none().0, origin.to_glib_none().0, merge_deployment.to_glib_none().0, mut_override(opts.to_glib_none().0), &mut out_new_deployment, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(out_new_deployment)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sysroot_try_lock")] + pub fn try_lock(&self) -> Result<bool, glib::Error> { + unsafe { + let mut out_acquired = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_try_lock(self.to_glib_none().0, out_acquired.as_mut_ptr(), &mut error); + let out_acquired = out_acquired.assume_init(); + if error.is_null() { Ok(from_glib(out_acquired)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sysroot_unload")] + pub fn unload(&self) { + unsafe { + ffi::ostree_sysroot_unload(self.to_glib_none().0); + } + } + + #[doc(alias = "ostree_sysroot_unlock")] + pub fn unlock(&self) { + unsafe { + ffi::ostree_sysroot_unlock(self.to_glib_none().0); + } + } + + #[doc(alias = "ostree_sysroot_write_deployments")] + pub fn write_deployments<P: IsA<gio::Cancellable>>(&self, new_deployments: &[Deployment], cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_write_deployments(self.to_glib_none().0, new_deployments.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[cfg(any(feature = "v2017_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_4")))] + #[doc(alias = "ostree_sysroot_write_deployments_with_options")] + pub fn write_deployments_with_options<P: IsA<gio::Cancellable>>(&self, new_deployments: &[Deployment], opts: &SysrootWriteDeploymentsOpts, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_write_deployments_with_options(self.to_glib_none().0, new_deployments.to_glib_none().0, mut_override(opts.to_glib_none().0), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sysroot_write_origin_file")] + pub fn write_origin_file<P: IsA<gio::Cancellable>>(&self, deployment: &Deployment, new_origin: Option<&glib::KeyFile>, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_write_origin_file(self.to_glib_none().0, deployment.to_glib_none().0, new_origin.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sysroot_get_deployment_origin_path")] + #[doc(alias = "get_deployment_origin_path")] + pub fn deployment_origin_path<P: IsA<gio::File>>(deployment_path: &P) -> Option<gio::File> { + unsafe { + from_glib_full(ffi::ostree_sysroot_get_deployment_origin_path(deployment_path.as_ref().to_glib_none().0)) + } + } + + #[cfg(any(feature = "v2017_10", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_10")))] + #[doc(alias = "journal-msg")] + pub fn connect_journal_msg<F: Fn(&Self, &str) + 'static>(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn journal_msg_trampoline<F: Fn(&Sysroot, &str) + 'static>(this: *mut ffi::OstreeSysroot, msg: *mut libc::c_char, f: glib::ffi::gpointer) { + let f: &F = &*(f as *const F); + f(&from_glib_borrow(this), &glib::GString::from_glib_borrow(msg)) + } + unsafe { + let f: Box_<F> = Box_::new(f); + connect_raw(self.as_ptr() as *mut _, b"journal-msg\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>(journal_msg_trampoline::<F> as *const ())), Box_::into_raw(f)) + } + } +} + +impl fmt::Display for Sysroot { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("Sysroot") + } +} diff --git a/rust-bindings/src/auto/sysroot_upgrader.rs b/rust-bindings/src/auto/sysroot_upgrader.rs new file mode 100644 index 0000000000..0e932534e0 --- /dev/null +++ b/rust-bindings/src/auto/sysroot_upgrader.rs @@ -0,0 +1,159 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use crate::AsyncProgress; +use crate::Repo; +use crate::RepoPullFlags; +use crate::Sysroot; +use crate::SysrootUpgraderFlags; +use crate::SysrootUpgraderPullFlags; +use glib::object::IsA; +use glib::object::ObjectType as ObjectType_; +use glib::translate::*; +use glib::StaticType; +use std::fmt; +use std::mem; +use std::ptr; + +glib::wrapper! { + #[doc(alias = "OstreeSysrootUpgrader")] + pub struct SysrootUpgrader(Object<ffi::OstreeSysrootUpgrader>); + + match fn { + type_ => || ffi::ostree_sysroot_upgrader_get_type(), + } +} + +impl SysrootUpgrader { + #[doc(alias = "ostree_sysroot_upgrader_new")] + pub fn new<P: IsA<gio::Cancellable>>(sysroot: &Sysroot, cancellable: Option<&P>) -> Result<SysrootUpgrader, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_sysroot_upgrader_new(sysroot.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sysroot_upgrader_new_for_os")] + #[doc(alias = "new_for_os")] + pub fn for_os<P: IsA<gio::Cancellable>>(sysroot: &Sysroot, osname: Option<&str>, cancellable: Option<&P>) -> Result<SysrootUpgrader, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_sysroot_upgrader_new_for_os(sysroot.to_glib_none().0, osname.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sysroot_upgrader_new_for_os_with_flags")] + #[doc(alias = "new_for_os_with_flags")] + pub fn for_os_with_flags<P: IsA<gio::Cancellable>>(sysroot: &Sysroot, osname: Option<&str>, flags: SysrootUpgraderFlags, cancellable: Option<&P>) -> Result<SysrootUpgrader, glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let ret = ffi::ostree_sysroot_upgrader_new_for_os_with_flags(sysroot.to_glib_none().0, osname.to_glib_none().0, flags.into_glib(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(from_glib_full(ret)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sysroot_upgrader_deploy")] + pub fn deploy<P: IsA<gio::Cancellable>>(&self, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_upgrader_deploy(self.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sysroot_upgrader_dup_origin")] + pub fn dup_origin(&self) -> Option<glib::KeyFile> { + unsafe { + from_glib_full(ffi::ostree_sysroot_upgrader_dup_origin(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_sysroot_upgrader_get_origin")] + #[doc(alias = "get_origin")] + pub fn origin(&self) -> Option<glib::KeyFile> { + unsafe { + from_glib_none(ffi::ostree_sysroot_upgrader_get_origin(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_sysroot_upgrader_get_origin_description")] + #[doc(alias = "get_origin_description")] + pub fn origin_description(&self) -> Option<glib::GString> { + unsafe { + from_glib_full(ffi::ostree_sysroot_upgrader_get_origin_description(self.to_glib_none().0)) + } + } + + #[doc(alias = "ostree_sysroot_upgrader_pull")] + pub fn pull<P: IsA<gio::Cancellable>>(&self, flags: RepoPullFlags, upgrader_flags: SysrootUpgraderPullFlags, progress: Option<&AsyncProgress>, cancellable: Option<&P>) -> Result<bool, glib::Error> { + unsafe { + let mut out_changed = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_upgrader_pull(self.to_glib_none().0, flags.into_glib(), upgrader_flags.into_glib(), progress.to_glib_none().0, out_changed.as_mut_ptr(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + let out_changed = out_changed.assume_init(); + if error.is_null() { Ok(from_glib(out_changed)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sysroot_upgrader_pull_one_dir")] + pub fn pull_one_dir<P: IsA<gio::Cancellable>>(&self, dir_to_pull: &str, flags: RepoPullFlags, upgrader_flags: SysrootUpgraderPullFlags, progress: Option<&AsyncProgress>, cancellable: Option<&P>) -> Result<bool, glib::Error> { + unsafe { + let mut out_changed = mem::MaybeUninit::uninit(); + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_upgrader_pull_one_dir(self.to_glib_none().0, dir_to_pull.to_glib_none().0, flags.into_glib(), upgrader_flags.into_glib(), progress.to_glib_none().0, out_changed.as_mut_ptr(), cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + let out_changed = out_changed.assume_init(); + if error.is_null() { Ok(from_glib(out_changed)) } else { Err(from_glib_full(error)) } + } + } + + #[doc(alias = "ostree_sysroot_upgrader_set_origin")] + pub fn set_origin<P: IsA<gio::Cancellable>>(&self, origin: Option<&glib::KeyFile>, cancellable: Option<&P>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_upgrader_set_origin(self.to_glib_none().0, origin.to_glib_none().0, cancellable.map(|p| p.as_ref()).to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } + + pub fn flags(&self) -> SysrootUpgraderFlags { + unsafe { + let mut value = glib::Value::from_type(<SysrootUpgraderFlags as StaticType>::static_type()); + glib::gobject_ffi::g_object_get_property(self.as_ptr() as *mut glib::gobject_ffi::GObject, b"flags\0".as_ptr() as *const _, value.to_glib_none_mut().0); + value.get().expect("Return Value for property `flags` getter") + } + } + + pub fn osname(&self) -> Option<glib::GString> { + unsafe { + let mut value = glib::Value::from_type(<glib::GString as StaticType>::static_type()); + glib::gobject_ffi::g_object_get_property(self.as_ptr() as *mut glib::gobject_ffi::GObject, b"osname\0".as_ptr() as *const _, value.to_glib_none_mut().0); + value.get().expect("Return Value for property `osname` getter") + } + } + + pub fn sysroot(&self) -> Option<Sysroot> { + unsafe { + let mut value = glib::Value::from_type(<Sysroot as StaticType>::static_type()); + glib::gobject_ffi::g_object_get_property(self.as_ptr() as *mut glib::gobject_ffi::GObject, b"sysroot\0".as_ptr() as *const _, value.to_glib_none_mut().0); + value.get().expect("Return Value for property `sysroot` getter") + } + } + + #[doc(alias = "ostree_sysroot_upgrader_check_timestamps")] + pub fn check_timestamps(repo: &Repo, from_rev: &str, to_rev: &str) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_sysroot_upgrader_check_timestamps(repo.to_glib_none().0, from_rev.to_glib_none().0, to_rev.to_glib_none().0, &mut error); + if error.is_null() { Ok(()) } else { Err(from_glib_full(error)) } + } + } +} + +impl fmt::Display for SysrootUpgrader { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("SysrootUpgrader") + } +} diff --git a/rust-bindings/src/auto/versions.txt b/rust-bindings/src/auto/versions.txt new file mode 100644 index 0000000000..5a1560025c --- /dev/null +++ b/rust-bindings/src/auto/versions.txt @@ -0,0 +1,2 @@ +Generated by gir (https://github.com/gtk-rs/gir @ e8f82cf6) +from gir-files diff --git a/rust-bindings/src/checksum.rs b/rust-bindings/src/checksum.rs new file mode 100644 index 0000000000..4cc981645d --- /dev/null +++ b/rust-bindings/src/checksum.rs @@ -0,0 +1,245 @@ +use glib::ffi::{g_free, g_malloc0, gpointer}; +use glib::translate::{FromGlibPtrFull, FromGlibPtrNone}; +use once_cell::sync::OnceCell; +use std::ptr::copy_nonoverlapping; + +const BYTES_LEN: usize = ffi::OSTREE_SHA256_DIGEST_LEN as usize; + +static BASE64_CONFIG: OnceCell<radix64::CustomConfig> = OnceCell::new(); + +fn base64_config() -> &'static radix64::CustomConfig { + BASE64_CONFIG.get_or_init(|| { + radix64::configs::CustomConfigBuilder::with_alphabet( + // modified base64 alphabet used by ostree (uses _ instead of /) + "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+_", + ) + .no_padding() + .build() + .unwrap() + }) +} + +/// Error returned from parsing a checksum. +#[derive(Debug, thiserror::Error)] +pub enum ChecksumError { + /// Invalid hex checksum string. + #[error("invalid hex checksum string")] + InvalidHexString, + /// Invalid base64 checksum string + #[error("invalid base64 checksum string")] + InvalidBase64String, +} + +/// A binary SHA256 checksum. +#[derive(Debug)] +pub struct Checksum { + bytes: *mut [u8; BYTES_LEN], +} + +// Safety: just a pointer to some memory owned by the type itself. +unsafe impl Send for Checksum {} + +impl Checksum { + /// Create a `Checksum` from a byte array. + /// + /// This copies the array. + pub fn from_bytes(bytes: &[u8; BYTES_LEN]) -> Checksum { + let mut checksum = Checksum::zeroed(); + checksum.as_mut().copy_from_slice(bytes); + checksum + } + + /// Create a `Checksum` from a hexadecimal SHA256 string. + pub fn from_hex(hex_checksum: &str) -> Result<Checksum, ChecksumError> { + let mut checksum = Checksum::zeroed(); + match hex::decode_to_slice(hex_checksum, checksum.as_mut()) { + Ok(_) => Ok(checksum), + Err(_) => Err(ChecksumError::InvalidHexString), + } + } + + /// Create a `Checksum` from a base64-encoded String. + pub fn from_base64(b64_checksum: &str) -> Result<Checksum, ChecksumError> { + let mut checksum = Checksum::zeroed(); + match base64_config().decode_slice(b64_checksum, checksum.as_mut()) { + Ok(BYTES_LEN) => Ok(checksum), + Ok(_) => Err(ChecksumError::InvalidBase64String), + Err(_) => Err(ChecksumError::InvalidBase64String), + } + } + + /// Convert checksum to hex-encoded string. + pub fn to_hex(&self) -> String { + hex::encode(self.as_slice()) + } + + /// Convert checksum to base64 string. + pub fn to_base64(&self) -> String { + base64_config().encode(self.as_slice()) + } + + /// Create a `Checksum` value, taking ownership of the given memory location. + /// + /// # Safety + /// `bytes` must point to an initialized 32-byte memory location that is freeable with + /// `g_free` (this is e.g. the case if the memory was allocated with `g_malloc`). The returned + /// value takes ownership of the memory and frees it on drop. + unsafe fn new(bytes: *mut [u8; BYTES_LEN]) -> Checksum { + assert!(!bytes.is_null()); + Checksum { bytes } + } + + /// Create a `Checksum` value initialized to 0. + fn zeroed() -> Checksum { + let bytes = unsafe { g_malloc0(BYTES_LEN) as *mut [u8; BYTES_LEN] }; + Checksum { bytes } + } + + /// Get a shared reference to the inner array. + fn as_slice(&self) -> &[u8; BYTES_LEN] { + unsafe { &(*self.bytes) } + } + + /// Get a mutable reference to the inner array. + fn as_mut(&mut self) -> &mut [u8; BYTES_LEN] { + unsafe { &mut (*self.bytes) } + } +} + +impl Drop for Checksum { + fn drop(&mut self) { + unsafe { + g_free(self.bytes as gpointer); + } + } +} + +impl Clone for Checksum { + fn clone(&self) -> Self { + unsafe { Checksum::from_glib_none(self.bytes) } + } +} + +impl PartialEq for Checksum { + fn eq(&self, other: &Self) -> bool { + unsafe { + let ret = + ffi::ostree_cmp_checksum_bytes(self.bytes as *const u8, other.bytes as *const u8); + ret == 0 + } + } +} + +impl Eq for Checksum {} + +impl std::fmt::Display for Checksum { + fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result { + write!(f, "{}", self.to_hex()) + } +} + +impl FromGlibPtrFull<*mut [u8; BYTES_LEN]> for Checksum { + unsafe fn from_glib_full(ptr: *mut [u8; BYTES_LEN]) -> Self { + Checksum::new(ptr) + } +} + +impl FromGlibPtrFull<*mut [*mut u8; BYTES_LEN]> for Checksum { + unsafe fn from_glib_full(ptr: *mut [*mut u8; BYTES_LEN]) -> Self { + Checksum::new(ptr as *mut u8 as *mut [u8; BYTES_LEN]) + } +} + +impl FromGlibPtrFull<*mut u8> for Checksum { + unsafe fn from_glib_full(ptr: *mut u8) -> Self { + Checksum::new(ptr as *mut [u8; BYTES_LEN]) + } +} + +impl FromGlibPtrNone<*mut [u8; BYTES_LEN]> for Checksum { + unsafe fn from_glib_none(ptr: *mut [u8; BYTES_LEN]) -> Self { + let checksum = Checksum::zeroed(); + // copy one array of BYTES_LEN elements + copy_nonoverlapping(ptr, checksum.bytes, 1); + checksum + } +} + +#[cfg(test)] +mod tests { + use super::*; + use glib::ffi::g_malloc0; + use glib::translate::from_glib_full; + + const CHECKSUM_BYTES: &[u8; BYTES_LEN] = b"\xbf\x87S\x06x>\xfd\xc5\xbc\xab7\xea\x10\xb6\xcaN\x9bj\xea\x8b\x94X\r\x0c\xa9J\xf1 V\\\x0e\x8a"; + const CHECKSUM_HEX: &str = "bf875306783efdc5bcab37ea10b6ca4e9b6aea8b94580d0ca94af120565c0e8a"; + const CHECKSUM_BASE64: &str = "v4dTBng+_cW8qzfqELbKTptq6ouUWA0MqUrxIFZcDoo"; + + #[test] + fn should_create_checksum_from_bytes_taking_ownership() { + let bytes = unsafe { g_malloc0(BYTES_LEN) } as *mut u8; + let checksum: Checksum = unsafe { from_glib_full(bytes) }; + assert_eq!(checksum.to_string(), "00".repeat(BYTES_LEN)); + } + + #[test] + fn should_create_checksum_from_bytes() { + let checksum = Checksum::from_bytes(CHECKSUM_BYTES); + assert_eq!(checksum.to_hex(), CHECKSUM_HEX); + } + + #[test] + fn should_parse_checksum_string_to_bytes() { + let csum = Checksum::from_hex(CHECKSUM_HEX).unwrap(); + assert_eq!(csum.to_string(), CHECKSUM_HEX); + } + + #[test] + fn should_fail_for_too_short_hex_string() { + let result = Checksum::from_hex(&"FF".repeat(31)); + assert!(result.is_err()); + } + + #[test] + fn should_convert_checksum_to_base64() { + let csum = Checksum::from_hex(CHECKSUM_HEX).unwrap(); + assert_eq!(csum.to_base64(), CHECKSUM_BASE64); + } + + #[test] + fn should_convert_base64_string_to_checksum() { + let csum = Checksum::from_base64(CHECKSUM_BASE64).unwrap(); + assert_eq!(csum.to_base64(), CHECKSUM_BASE64); + assert_eq!(csum.to_string(), CHECKSUM_HEX); + } + + #[test] + fn should_fail_for_too_short_b64_string() { + let result = Checksum::from_base64("abcdefghi"); + assert!(result.is_err()); + } + + #[test] + fn should_fail_for_invalid_base64_string() { + let result = Checksum::from_base64(&"\n".repeat(43)); + assert!(result.is_err()); + } + + #[test] + fn should_compare_checksums() { + let csum = Checksum::from_hex(CHECKSUM_HEX).unwrap(); + assert_eq!(csum, csum); + let csum2 = Checksum::from_hex(CHECKSUM_HEX).unwrap(); + assert_eq!(csum2, csum); + } + + #[test] + fn should_clone_value() { + let csum = Checksum::from_hex(CHECKSUM_HEX).unwrap(); + let csum2 = csum.clone(); + assert_eq!(csum2, csum); + let csum3 = csum2.clone(); + assert_eq!(csum3, csum); + assert_eq!(csum3, csum2); + } +} diff --git a/rust-bindings/src/collection_ref.rs b/rust-bindings/src/collection_ref.rs new file mode 100644 index 0000000000..0fb28deb49 --- /dev/null +++ b/rust-bindings/src/collection_ref.rs @@ -0,0 +1,78 @@ +use crate::CollectionRef; +use glib::translate::ToGlibPtr; +use std::ffi::CStr; + +trait AsNonnullPtr +where + Self: Sized, +{ + fn as_nonnull_ptr(&self) -> Option<Self>; +} + +impl<T> AsNonnullPtr for *mut T { + fn as_nonnull_ptr(&self) -> Option<Self> { + if self.is_null() { + None + } else { + Some(*self) + } + } +} + +impl CollectionRef { + /// Get the collection ID from this `CollectionRef`. + /// + /// # Returns + /// Since the value may not be valid UTF-8, `&CStr` is returned. You can safely turn it into a + /// `&str` using the `as_str` method. + /// + /// If no collection ID was set in the `CollectionRef`, `None` is returned. + pub fn collection_id(&self) -> Option<&CStr> { + let inner = self.to_glib_none(); + unsafe { + (*inner.0) + .collection_id + .as_nonnull_ptr() + .map(|ptr| CStr::from_ptr(ptr)) + } + } + + /// Get the ref name from this `CollectionRef`. + /// + /// # Returns + /// Since the value may not be valid UTF-8, `&CStr` is returned. You can safely turn it into a + /// `&str` using the `as_str` method. + pub fn ref_name(&self) -> &CStr { + let inner = self.to_glib_none(); + unsafe { CStr::from_ptr((*inner.0).ref_name) } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn should_get_collection_id() { + let collection_ref = CollectionRef::new(Some("collection.id"), "ref").unwrap(); + let id = collection_ref.collection_id().unwrap().to_str().unwrap(); + + assert_eq!(id, "collection.id"); + } + + #[test] + fn should_get_none_collection_id() { + let collection_ref = CollectionRef::new(None, "ref").unwrap(); + let id = collection_ref.collection_id(); + + assert_eq!(id, None); + } + + #[test] + fn should_get_ref_name() { + let collection_ref = CollectionRef::new(Some("collection.id"), "ref-name").unwrap(); + let ref_name = collection_ref.ref_name().to_str().unwrap(); + + assert_eq!(ref_name, "ref-name"); + } +} diff --git a/rust-bindings/src/commit_sizes_entry.rs b/rust-bindings/src/commit_sizes_entry.rs new file mode 100644 index 0000000000..d96b4f0fa0 --- /dev/null +++ b/rust-bindings/src/commit_sizes_entry.rs @@ -0,0 +1,48 @@ +use crate::{auto::CommitSizesEntry, auto::ObjectType}; +use glib::{ + translate::{FromGlib, FromGlibPtrNone, ToGlibPtr}, + GString, +}; + +impl CommitSizesEntry { + /// Object checksum as hex string. + pub fn checksum(&self) -> GString { + let underlying = self.to_glib_none(); + unsafe { GString::from_glib_none((*underlying.0).checksum) } + } + + /// The object type. + pub fn objtype(&self) -> ObjectType { + let underlying = self.to_glib_none(); + unsafe { ObjectType::from_glib((*underlying.0).objtype) } + } + + /// Unpacked object size. + pub fn unpacked(&self) -> u64 { + let underlying = self.to_glib_none(); + unsafe { (*underlying.0).unpacked } + } + + /// Compressed object size. + pub fn archived(&self) -> u64 { + let underlying = self.to_glib_none(); + unsafe { (*underlying.0).archived } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + const CHECKSUM_STRING: &str = + "bf875306783efdc5bcab37ea10b6ca4e9b6aea8b94580d0ca94af120565c0e8a"; + + #[test] + fn should_get_values_from_commit_sizes_entry() { + let entry = CommitSizesEntry::new(CHECKSUM_STRING, ObjectType::Commit, 15, 16).unwrap(); + assert_eq!(entry.checksum(), CHECKSUM_STRING); + assert_eq!(entry.objtype(), ObjectType::Commit); + assert_eq!(entry.unpacked(), 15); + assert_eq!(entry.archived(), 16); + } +} diff --git a/rust-bindings/src/constants.rs b/rust-bindings/src/constants.rs new file mode 100644 index 0000000000..6586e7b6b9 --- /dev/null +++ b/rust-bindings/src/constants.rs @@ -0,0 +1,3 @@ +/// Metadata key corresponding to the Docker/OCI `CMD` verb. +/// <https://github.com/opencontainers/image-spec/blob/main/config.md> +pub const COMMIT_META_CONTAINER_CMD: &str = "ostree.container-cmd"; diff --git a/rust-bindings/src/core.rs b/rust-bindings/src/core.rs new file mode 100644 index 0000000000..5e294b1b65 --- /dev/null +++ b/rust-bindings/src/core.rs @@ -0,0 +1,48 @@ +//! Hand written bindings for ostree-core.h + +use glib::VariantDict; + +/// The type of a commit object: `(a{sv}aya(say)sstayay)` +pub type CommitVariantType = ( + VariantDict, + Vec<u8>, + Vec<(String, Vec<u8>)>, + String, + String, + u64, + Vec<u8>, + Vec<u8>, +); + +/// The type of a dirtree object: `(a(say)a(sayay))` +pub type TreeVariantType = (Vec<(String, Vec<u8>)>, Vec<(String, Vec<u8>, Vec<u8>)>); + +/// The type of a directory metadata object: `(uuua(ayay))` +pub type DirmetaVariantType = (u32, u32, u32, Vec<(Vec<u8>, Vec<u8>)>); + +/// Parsed representation of directory metadata. +pub struct DirMetaParsed { + /// The user ID. + pub uid: u32, + /// The group ID. + pub gid: u32, + /// The Unix mode, including file type flag. + pub mode: u32, + /// Extended attributes. + pub xattrs: Vec<(Vec<u8>, Vec<u8>)>, +} + +impl DirMetaParsed { + /// Parse a directory metadata variant; must be of type `(uuua(ayay))`. + pub fn from_variant( + v: &glib::Variant, + ) -> Result<DirMetaParsed, glib::variant::VariantTypeMismatchError> { + let (uid, gid, mode, xattrs) = v.try_get::<crate::DirmetaVariantType>()?; + Ok(DirMetaParsed { + uid: u32::from_be(uid), + gid: u32::from_be(gid), + mode: u32::from_be(mode), + xattrs, + }) + } +} diff --git a/rust-bindings/src/functions.rs b/rust-bindings/src/functions.rs new file mode 100644 index 0000000000..309a1799fe --- /dev/null +++ b/rust-bindings/src/functions.rs @@ -0,0 +1,158 @@ +#[cfg(any(feature = "v2017_13", feature = "dox"))] +use crate::ChecksumFlags; +use crate::{Checksum, ObjectType}; +use glib::ffi::GFALSE; +use glib::{prelude::*, translate::*}; +use std::{future::Future, mem::MaybeUninit, pin::Pin, ptr}; + +/// Compute the SHA-256 checksum of a file. +pub fn checksum_file<P: IsA<gio::File>, Q: IsA<gio::Cancellable>>( + f: &P, + objtype: ObjectType, + cancellable: Option<&Q>, +) -> Result<Checksum, Box<dyn std::error::Error>> { + unsafe { + let mut out_csum = ptr::null_mut(); + let mut error = ptr::null_mut(); + let ret = ffi::ostree_checksum_file( + f.as_ref().to_glib_none().0, + objtype.into_glib(), + &mut out_csum, + cancellable.map(|p| p.as_ref()).to_glib_none().0, + &mut error, + ); + checksum_file_error(out_csum, error, ret) + } +} + +/// Asynchronously compute the SHA-256 checksum of a file. +pub fn checksum_file_async< + P: IsA<gio::File>, + Q: IsA<gio::Cancellable>, + R: FnOnce(Result<Checksum, Box<dyn std::error::Error>>) + Send + 'static, +>( + f: &P, + objtype: ObjectType, + io_priority: i32, + cancellable: Option<&Q>, + callback: R, +) { + let user_data: Box<R> = Box::new(callback); + unsafe extern "C" fn checksum_file_async_trampoline< + R: FnOnce(Result<Checksum, Box<dyn std::error::Error>>) + Send + 'static, + >( + _source_object: *mut glib::gobject_ffi::GObject, + res: *mut gio::ffi::GAsyncResult, + user_data: glib::ffi::gpointer, + ) { + let mut error = ptr::null_mut(); + let mut out_csum = MaybeUninit::uninit(); + let ret = ffi::ostree_checksum_file_async_finish( + _source_object as *mut _, + res, + out_csum.as_mut_ptr(), + &mut error, + ); + let out_csum = out_csum.assume_init(); + let result = checksum_file_error(out_csum, error, ret); + let callback: Box<R> = Box::from_raw(user_data as *mut _); + callback(result); + } + let callback = checksum_file_async_trampoline::<R>; + unsafe { + ffi::ostree_checksum_file_async( + f.as_ref().to_glib_none().0, + objtype.into_glib(), + io_priority, + cancellable.map(|p| p.as_ref()).to_glib_none().0, + Some(callback), + Box::into_raw(user_data) as *mut _, + ); + } +} + +/// Asynchronously compute the SHA-256 checksum of a file. +#[allow(clippy::type_complexity)] +pub fn checksum_file_async_future<P: IsA<gio::File> + Clone + 'static>( + f: &P, + objtype: ObjectType, + io_priority: i32, +) -> Pin<Box<dyn Future<Output = Result<Checksum, Box<dyn std::error::Error>>> + 'static>> { + let f = f.clone(); + Box::pin(gio::GioFuture::new(&f, move |f, cancellable, send| { + checksum_file_async(f, objtype, io_priority, Some(cancellable), move |res| { + send.resolve(res); + }); + })) +} + +/// Compute the OSTree checksum of a content object. +pub fn checksum_file_from_input<P: IsA<gio::InputStream>, Q: IsA<gio::Cancellable>>( + file_info: &gio::FileInfo, + xattrs: Option<&glib::Variant>, + in_: Option<&P>, + objtype: ObjectType, + cancellable: Option<&Q>, +) -> Result<Checksum, Box<dyn std::error::Error>> { + unsafe { + let mut out_csum = ptr::null_mut(); + let mut error = ptr::null_mut(); + let ret = ffi::ostree_checksum_file_from_input( + file_info.to_glib_none().0, + xattrs.to_glib_none().0, + in_.map(|p| p.as_ref()).to_glib_none().0, + objtype.into_glib(), + &mut out_csum, + cancellable.map(|p| p.as_ref()).to_glib_none().0, + &mut error, + ); + checksum_file_error(out_csum, error, ret) + } +} + +/// Compute the OSTree checksum of a file. +#[cfg(any(feature = "v2017_13", feature = "dox"))] +pub fn checksum_file_at<P: IsA<gio::Cancellable>>( + dfd: i32, + path: &std::path::Path, + stbuf: Option<&libc::stat>, + objtype: ObjectType, + flags: ChecksumFlags, + cancellable: Option<&P>, +) -> Result<glib::GString, glib::Error> { + unsafe { + let mut out_checksum = ptr::null_mut(); + let mut error = ptr::null_mut(); + ffi::ostree_checksum_file_at( + dfd, + path.to_glib_none().0, + stbuf + .map(|p| p as *const libc::stat as *mut libc::stat) + .unwrap_or(ptr::null_mut()), + objtype.into_glib(), + flags.into_glib(), + &mut out_checksum, + cancellable.map(|p| p.as_ref()).to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(from_glib_full(out_checksum)) + } else { + Err(from_glib_full(error)) + } + } +} + +unsafe fn checksum_file_error( + out_csum: *mut [*mut u8; 32], + error: *mut glib::ffi::GError, + ret: i32, +) -> Result<Checksum, Box<dyn std::error::Error>> { + if !error.is_null() { + Err(Box::<glib::Error>::new(from_glib_full(error))) + } else if ret == GFALSE { + Err(Box::new(glib::bool_error!("unknown error"))) + } else { + Ok(Checksum::from_glib_full(out_csum)) + } +} diff --git a/rust-bindings/src/kernel_args.rs b/rust-bindings/src/kernel_args.rs new file mode 100644 index 0000000000..ea7fc532fd --- /dev/null +++ b/rust-bindings/src/kernel_args.rs @@ -0,0 +1,228 @@ +use ffi::OstreeKernelArgs; +#[cfg(any(feature = "v2019_3", feature = "dox"))] +use glib::object::IsA; +use glib::translate::*; +#[cfg(any(feature = "v2019_3", feature = "dox"))] +use glib::GString; +use std::fmt; +use std::ptr; + +glib::wrapper! { + /// Kernel arguments. + #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] + pub struct KernelArgs(Boxed<ffi::OstreeKernelArgs>); + + match fn { + copy => |_ptr| unimplemented!(), + free => |ptr| ffi::ostree_kernel_args_free(ptr), + } +} + +impl KernelArgs { + /// Add a kernel argument. + #[cfg(any(feature = "v2019_3", feature = "dox"))] + pub fn append(&mut self, arg: &str) { + unsafe { + ffi::ostree_kernel_args_append(self.to_glib_none_mut().0, arg.to_glib_none().0); + } + } + + /// Add multiple kernel arguments. + #[cfg(any(feature = "v2019_3", feature = "dox"))] + pub fn append_argv(&mut self, argv: &[&str]) { + unsafe { + ffi::ostree_kernel_args_append_argv(self.to_glib_none_mut().0, argv.to_glib_none().0); + } + } + + /// Appends each argument that does not have one of `prefixes`. + #[cfg(any(feature = "v2019_3", feature = "dox"))] + pub fn append_argv_filtered(&mut self, argv: &[&str], prefixes: &[&str]) { + unsafe { + ffi::ostree_kernel_args_append_argv_filtered( + self.to_glib_none_mut().0, + argv.to_glib_none().0, + prefixes.to_glib_none().0, + ); + } + } + + /// Append the entire contents of the currently booted kernel commandline. + #[cfg(any(feature = "v2019_3", feature = "dox"))] + pub fn append_proc_cmdline<P: IsA<gio::Cancellable>>( + &mut self, + cancellable: Option<&P>, + ) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_kernel_args_append_proc_cmdline( + self.to_glib_none_mut().0, + cancellable.map(|p| p.as_ref()).to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } + } + + /// Remove a kernel argument. + pub fn delete(&mut self, arg: &str) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_kernel_args_delete( + self.to_glib_none_mut().0, + arg.to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } + } + + /// Remove a kernel argument. + #[cfg(any(feature = "v2019_3", feature = "dox"))] + pub fn delete_key_entry(&mut self, key: &str) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_kernel_args_delete_key_entry( + self.to_glib_none_mut().0, + key.to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } + } + + /// Given `foo`, return the last the value of a `foo=bar` key as `bar`. + #[cfg(any(feature = "v2019_3", feature = "dox"))] + pub fn get_last_value(&self, key: &str) -> Option<GString> { + unsafe { + from_glib_none(ffi::ostree_kernel_args_get_last_value( + self.to_glib_none().0 as *mut OstreeKernelArgs, + key.to_glib_none().0, + )) + } + } + + /// Replace any existing `foo=bar` with `foo=other` e.g. + #[cfg(any(feature = "v2019_3", feature = "dox"))] + pub fn new_replace(&mut self, arg: &str) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = ffi::ostree_kernel_args_new_replace( + self.to_glib_none_mut().0, + arg.to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } + } + + /// Append from a whitespace-separated string. + #[cfg(any(feature = "v2019_3", feature = "dox"))] + pub fn parse_append(&mut self, options: &str) { + unsafe { + ffi::ostree_kernel_args_parse_append( + self.to_glib_none_mut().0, + options.to_glib_none().0, + ); + } + } + + /// Replace a kernel argument. + #[cfg(any(feature = "v2019_3", feature = "dox"))] + pub fn replace(&mut self, arg: &str) { + unsafe { + ffi::ostree_kernel_args_replace(self.to_glib_none_mut().0, arg.to_glib_none().0); + } + } + + /// Replace multiple kernel arguments. + #[cfg(any(feature = "v2019_3", feature = "dox"))] + pub fn replace_argv(&mut self, argv: &[&str]) { + unsafe { + ffi::ostree_kernel_args_replace_argv(self.to_glib_none_mut().0, argv.to_glib_none().0); + } + } + + /// A duplicate of `replace`. + #[cfg(any(feature = "v2019_3", feature = "dox"))] + pub fn replace_take(&mut self, arg: &str) { + unsafe { + ffi::ostree_kernel_args_replace_take(self.to_glib_none_mut().0, arg.to_glib_full()); + } + } + + /// Convert the kernel arguments to a string. + #[cfg(any(feature = "v2019_3", feature = "dox"))] + fn to_gstring(&self) -> GString { + unsafe { + from_glib_full(ffi::ostree_kernel_args_to_string( + self.to_glib_none().0 as *mut OstreeKernelArgs, + )) + } + } + + /// Convert the kernel arguments to a string array. + #[cfg(any(feature = "v2019_3", feature = "dox"))] + pub fn to_strv(&self) -> Vec<GString> { + unsafe { + FromGlibPtrContainer::from_glib_full(ffi::ostree_kernel_args_to_strv( + self.to_glib_none().0 as *mut OstreeKernelArgs, + )) + } + } + + // Not needed + //pub fn cleanup(loc: /*Unimplemented*/Option<Fundamental: Pointer>) + + /// Parse the given string as kernel arguments. + #[cfg(any(feature = "v2019_3", feature = "dox"))] + pub fn from_string(options: &str) -> KernelArgs { + unsafe { + from_glib_full(ffi::ostree_kernel_args_from_string( + options.to_glib_none().0, + )) + } + } + + /// Create new empty kernel arguments. + #[cfg(any(feature = "v2019_3", feature = "dox"))] + pub fn new() -> KernelArgs { + unsafe { from_glib_full(ffi::ostree_kernel_args_new()) } + } +} + +#[cfg(any(feature = "v2019_3", feature = "dox"))] +impl Default for KernelArgs { + fn default() -> Self { + Self::new() + } +} + +impl fmt::Display for KernelArgs { + #[inline] + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "{}", self.to_gstring()) + } +} + +impl<T: AsRef<str>> From<T> for KernelArgs { + fn from(v: T) -> Self { + KernelArgs::from_string(v.as_ref()) + } +} diff --git a/rust-bindings/src/lib.rs b/rust-bindings/src/lib.rs new file mode 100644 index 0000000000..1cbeabd761 --- /dev/null +++ b/rust-bindings/src/lib.rs @@ -0,0 +1,95 @@ +//! # Rust bindings for **libostree** +//! +//! [libostree](https://ostree.readthedocs.io) is both a shared library and suite of command line +//! tools that combines a "git-like" model for committing and downloading bootable filesystem trees, +//! along with a layer for deploying them and managing the bootloader configuration. + +#![cfg_attr(feature = "dox", feature(doc_cfg))] +#![deny(unused_must_use)] +#![warn(missing_docs)] +#![warn(rustdoc::broken_intra_doc_links)] + +// Re-export our dependencies. See https://gtk-rs.org/blog/2021/06/22/new-release.html +// "Dependencies are re-exported". Users will need e.g. `gio::File`, so this avoids +// them needing to update matching versions. +#[cfg(feature = "cap-std-apis")] +pub use cap_std; +pub use ffi; +pub use gio; +pub use glib; + +/// Useful with `Repo::open_at()`. +pub use libc::AT_FDCWD; + +// code generated by gir +#[rustfmt::skip] +#[allow(clippy::all)] +#[allow(unused_imports)] +#[allow(missing_docs)] +mod auto; +pub use crate::auto::functions::*; +pub use crate::auto::*; + +// handwritten code +mod checksum; +pub use crate::checksum::*; +mod core; +pub use crate::core::*; +mod sysroot; +pub use crate::sysroot::*; + +mod constants; +pub use constants::*; + +#[cfg(any(feature = "v2018_6", feature = "dox"))] +mod collection_ref; +#[cfg(any(feature = "v2018_6", feature = "dox"))] +pub use crate::collection_ref::*; +mod functions; +pub use crate::functions::*; +mod mutable_tree; +pub use crate::mutable_tree::*; +#[cfg(any(feature = "v2019_3", feature = "dox"))] +mod kernel_args; +#[cfg(any(feature = "v2019_3", feature = "dox"))] +pub use crate::kernel_args::*; +mod object_name; +pub use crate::object_name::*; +mod object_details; +pub use crate::object_details::*; +mod repo; +pub use crate::repo::*; +#[cfg(any(feature = "v2016_8", feature = "dox"))] +mod repo_checkout_at_options; +#[cfg(any(feature = "v2016_8", feature = "dox"))] +pub use crate::repo_checkout_at_options::*; +mod repo_transaction_stats; +pub use repo_transaction_stats::RepoTransactionStats; +mod se_policy; +pub use crate::se_policy::*; +#[cfg(any(feature = "v2020_1", feature = "dox"))] +mod commit_sizes_entry; +#[cfg(any(feature = "v2020_1", feature = "dox"))] +pub use crate::commit_sizes_entry::*; +#[cfg(any(feature = "v2017_4", feature = "dox"))] +mod sysroot_write_deployments_opts; +#[cfg(any(feature = "v2017_4", feature = "dox"))] +pub use crate::sysroot_write_deployments_opts::*; +#[cfg(any(feature = "v2020_7", feature = "dox"))] +mod sysroot_deploy_tree_opts; +#[cfg(any(feature = "v2020_7", feature = "dox"))] +pub use crate::sysroot_deploy_tree_opts::SysrootDeployTreeOpts; + +// tests +#[cfg(test)] +mod tests; + +/// Prelude, intended for glob imports. +pub mod prelude { + pub use crate::auto::traits::*; + // See "Re-export dependencies above". + #[doc(hidden)] + pub use gio::prelude::*; + #[doc(hidden)] + pub use glib::prelude::*; +} diff --git a/rust-bindings/src/mutable_tree.rs b/rust-bindings/src/mutable_tree.rs new file mode 100644 index 0000000000..dd59217289 --- /dev/null +++ b/rust-bindings/src/mutable_tree.rs @@ -0,0 +1,46 @@ +use crate::MutableTree; +use glib::{self, translate::*}; +use std::collections::HashMap; + +impl MutableTree { + #[doc(alias = "ostree_mutable_tree_get_files")] + /// Create a copy of the files in this mutable tree. + /// Unlike the C version of this function, a copy is made because providing + /// read-write access would introduce the potential for use-after-free bugs. + pub fn copy_files(&self) -> HashMap<String, String> { + unsafe { + let v = ffi::ostree_mutable_tree_get_files(self.to_glib_none().0); + HashMap::from_glib_none_num(v, 1) + } + } + + #[doc(alias = "ostree_mutable_tree_get_subdirs")] + /// Create a copy of the directories in this mutable tree. + /// Unlike the C version of this function, a copy is made because providing + /// read-write access would introduce the potential for use-after-free bugs. + pub fn copy_subdirs(&self) -> HashMap<String, Self> { + use glib::ffi::gpointer; + + unsafe { + let v = ffi::ostree_mutable_tree_get_subdirs(self.to_glib_none().0); + unsafe extern "C" fn visit_hash_table( + key: gpointer, + value: gpointer, + hash_map: gpointer, + ) { + let key: String = from_glib_none(key as *const libc::c_char); + let value: MutableTree = from_glib_none(value as *const ffi::OstreeMutableTree); + let hash_map: &mut HashMap<String, MutableTree> = + &mut *(hash_map as *mut HashMap<String, MutableTree>); + hash_map.insert(key, value); + } + let mut map = HashMap::with_capacity(glib::ffi::g_hash_table_size(v) as usize); + glib::ffi::g_hash_table_foreach( + v, + Some(visit_hash_table), + &mut map as *mut HashMap<String, MutableTree> as *mut _, + ); + map + } + } +} diff --git a/rust-bindings/src/object_details.rs b/rust-bindings/src/object_details.rs new file mode 100644 index 0000000000..3dfb8432c4 --- /dev/null +++ b/rust-bindings/src/object_details.rs @@ -0,0 +1,44 @@ +use std::fmt::Display; +use std::fmt::Error; +use std::fmt::Formatter; + +/// Details of an object in an OSTree repo. It contains information about if +/// the object is "loose", and contains a list of pack file checksums in which +/// this object appears. +#[derive(Debug)] +pub struct ObjectDetails { + loose: bool, + object_appearances: Vec<String>, +} + +impl ObjectDetails { + /// Create a new `ObjectDetails` from a serialized representation. + pub fn new_from_variant(variant: glib::Variant) -> Option<ObjectDetails> { + let deserialize = variant.get::<(bool, Vec<String>)>()?; + Some(ObjectDetails { + loose: deserialize.0, + object_appearances: deserialize.1, + }) + } + + /// is object available "loose" + pub fn is_loose(&self) -> bool { + self.loose + } + + /// Provide list of pack file checksums in which the object appears + pub fn appearances(&self) -> &Vec<String> { + &self.object_appearances + } +} + +impl Display for ObjectDetails { + fn fmt(&self, f: &mut Formatter) -> Result<(), Error> { + write!( + f, + "Object is {} and appears in {} checksums", + if self.loose { "loose" } else { "not loose" }, + self.object_appearances.len() + ) + } +} diff --git a/rust-bindings/src/object_name.rs b/rust-bindings/src/object_name.rs new file mode 100644 index 0000000000..06ff8045fd --- /dev/null +++ b/rust-bindings/src/object_name.rs @@ -0,0 +1,115 @@ +use crate::ObjectType; +use crate::{object_name_deserialize, object_name_serialize, object_to_string}; +use glib::translate::*; +use glib::GString; +use std::fmt::Display; +use std::fmt::Error; +use std::fmt::Formatter; +use std::hash::Hash; +use std::hash::Hasher; + +fn hash_object_name(v: &glib::Variant) -> u32 { + unsafe { ffi::ostree_hash_object_name(v.to_glib_none().0 as glib::ffi::gconstpointer) } +} + +/// A reference to an object in an OSTree repo. It contains both a checksum and an +/// [ObjectType](enum.ObjectType.html) which together identify an object in a repository. +#[derive(Eq, Debug)] +pub struct ObjectName { + variant: glib::Variant, + checksum: GString, + object_type: ObjectType, +} + +impl ObjectName { + /// Create a new `ObjectName` from a serialized representation. + pub fn new_from_variant(variant: glib::Variant) -> ObjectName { + let deserialize = object_name_deserialize(&variant); + ObjectName { + variant, + checksum: deserialize.0, + object_type: deserialize.1, + } + } + + /// Create a new `ObjectName` with the given checksum and `ObjectType`. + pub fn new<S: Into<GString>>(checksum: S, object_type: ObjectType) -> ObjectName { + let checksum = checksum.into(); + let variant = object_name_serialize(checksum.as_str(), object_type) + .expect("type checks should make this safe"); + ObjectName { + variant, + checksum, + object_type, + } + } + + /// Return a reference to this `ObjectName`'s checksum string. + pub fn checksum(&self) -> &str { + self.checksum.as_str() + } + + /// Return this `ObjectName`'s `ObjectType`. + pub fn object_type(&self) -> ObjectType { + self.object_type + } + + /// Format this `ObjectName` as a string. + fn to_string(&self) -> GString { + object_to_string(self.checksum(), self.object_type()) + .expect("type checks should make this safe") + } +} + +impl Display for ObjectName { + fn fmt(&self, f: &mut Formatter) -> Result<(), Error> { + write!(f, "{}", self.to_string()) + } +} + +impl Hash for ObjectName { + fn hash<H: Hasher>(&self, state: &mut H) { + state.write_u32(hash_object_name(&self.variant)); + } +} + +impl PartialEq for ObjectName { + fn eq(&self, other: &ObjectName) -> bool { + self.checksum == other.checksum && self.object_type == other.object_type + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn should_stringify_object_name() { + let object_name = ObjectName::new("abcdef123456", ObjectType::DirTree); + let stringified = format!("{}", object_name); + assert_eq!(stringified, "abcdef123456.dirtree"); + } + + #[test] + fn same_values_should_be_equal() { + let a = ObjectName::new("abc123", ObjectType::File); + let b = ObjectName::new("abc123", ObjectType::File); + assert_eq!(a, b); + } + + #[test] + fn different_values_should_not_be_equal() { + let a = ObjectName::new("abc123", ObjectType::Commit); + let b = ObjectName::new("abc123", ObjectType::File); + assert_ne!(a, b); + } + + #[test] + fn should_create_object_name_from_variant() { + let object_name = ObjectName::new("123456", ObjectType::CommitMeta); + let from_variant = ObjectName::new_from_variant(object_name.variant.clone()); + assert_eq!(object_name, from_variant); + assert_eq!("123456", from_variant.checksum()); + assert_eq!(ObjectType::CommitMeta, from_variant.object_type()); + } +} diff --git a/rust-bindings/src/repo.rs b/rust-bindings/src/repo.rs new file mode 100644 index 0000000000..5d34f98b44 --- /dev/null +++ b/rust-bindings/src/repo.rs @@ -0,0 +1,524 @@ +#[cfg(any(feature = "v2016_4", feature = "dox"))] +use crate::RepoListRefsExtFlags; +#[cfg(feature = "cap-std-apis")] +use crate::RepoMode; +use crate::{Checksum, ObjectDetails, ObjectName, ObjectType, Repo, RepoTransactionStats}; +use ffi::OstreeRepoListObjectsFlags; +use glib::ffi as glib_sys; +use glib::{self, translate::*, Error, IsA}; +use std::{ + collections::{HashMap, HashSet}, + future::Future, + mem::MaybeUninit, + path::Path, + pin::Pin, + ptr, +}; + +unsafe extern "C" fn read_variant_table( + _key: glib_sys::gpointer, + value: glib_sys::gpointer, + hash_set: glib_sys::gpointer, +) { + let value: glib::Variant = from_glib_none(value as *const glib_sys::GVariant); + let set: &mut HashSet<ObjectName> = &mut *(hash_set as *mut HashSet<ObjectName>); + set.insert(ObjectName::new_from_variant(value)); +} + +unsafe extern "C" fn read_variant_object_map( + key: glib_sys::gpointer, + value: glib_sys::gpointer, + hash_set: glib_sys::gpointer, +) { + let key: glib::Variant = from_glib_none(key as *const glib_sys::GVariant); + let value: glib::Variant = from_glib_none(value as *const glib_sys::GVariant); + let set: &mut HashMap<ObjectName, ObjectDetails> = + &mut *(hash_set as *mut HashMap<ObjectName, ObjectDetails>); + if let Some(details) = ObjectDetails::new_from_variant(value) { + set.insert(ObjectName::new_from_variant(key), details); + } +} + +unsafe fn from_glib_container_variant_set(ptr: *mut glib_sys::GHashTable) -> HashSet<ObjectName> { + let mut set = HashSet::new(); + glib_sys::g_hash_table_foreach( + ptr, + Some(read_variant_table), + &mut set as *mut HashSet<ObjectName> as *mut _, + ); + glib_sys::g_hash_table_unref(ptr); + set +} + +unsafe fn from_glib_container_variant_map( + ptr: *mut glib_sys::GHashTable, +) -> HashMap<ObjectName, ObjectDetails> { + let mut set = HashMap::new(); + glib_sys::g_hash_table_foreach( + ptr, + Some(read_variant_object_map), + &mut set as *mut HashMap<ObjectName, ObjectDetails> as *mut _, + ); + glib_sys::g_hash_table_unref(ptr); + set +} + +/// An open transaction in the repository. +/// +/// This will automatically invoke [`ostree::Repo::abort_transaction`] when the value is dropped. +pub struct TransactionGuard<'a> { + /// Reference to the repository for this transaction. + repo: Option<&'a Repo>, +} + +impl<'a> TransactionGuard<'a> { + /// Returns a reference to the repository. + pub fn repo(&self) -> &Repo { + // SAFETY: This is only set to None in `commit`, which consumes self + self.repo.unwrap() + } + + /// Commit this transaction. + pub fn commit<P: IsA<gio::Cancellable>>( + mut self, + cancellable: Option<&P>, + ) -> Result<RepoTransactionStats, glib::Error> { + // Safety: This is the only function which mutates this option + let repo = self.repo.take().unwrap(); + repo.commit_transaction(cancellable) + } +} + +impl<'a> Drop for TransactionGuard<'a> { + fn drop(&mut self) { + if let Some(repo) = self.repo { + // TODO: better logging in ostree? + // See also https://github.com/ostreedev/ostree/issues/2413 + let _ = repo.abort_transaction(gio::NONE_CANCELLABLE); + } + } +} + +impl Repo { + /// Create a new `Repo` object for working with an OSTree repo at the given path. + pub fn new_for_path<P: AsRef<Path>>(path: P) -> Repo { + Repo::new(&gio::File::for_path(path.as_ref())) + } + + #[cfg(feature = "cap-std-apis")] + /// A version of [`open_at`] which uses cap-std. + pub fn open_at_dir(dir: &cap_std::fs::Dir, path: &str) -> Result<Repo, glib::Error> { + use std::os::unix::io::AsRawFd; + crate::Repo::open_at(dir.as_raw_fd(), path, gio::NONE_CANCELLABLE) + } + + #[cfg(feature = "cap-std-apis")] + /// A version of [`create_at`] which uses cap-std, and also returns the opened repo. + pub fn create_at_dir( + dir: &cap_std::fs::Dir, + path: &str, + mode: RepoMode, + options: Option<&glib::Variant>, + ) -> Result<Repo, glib::Error> { + use std::os::unix::io::AsRawFd; + crate::Repo::create_at(dir.as_raw_fd(), path, mode, options, gio::NONE_CANCELLABLE)?; + Repo::open_at_dir(dir, path) + } + + /// A wrapper for [`prepare_transaction`] which ensures the transaction will be aborted when the guard goes out of scope. + pub fn auto_transaction<P: IsA<gio::Cancellable>>( + &self, + cancellable: Option<&P>, + ) -> Result<TransactionGuard, glib::Error> { + let _ = self.prepare_transaction(cancellable)?; + Ok(TransactionGuard { repo: Some(self) }) + } + + /// Return a copy of the directory file descriptor for this repository. + #[cfg(any(feature = "v2016_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] + pub fn dfd_as_file(&self) -> std::io::Result<std::fs::File> { + use std::os::unix::prelude::FromRawFd; + use std::os::unix::prelude::IntoRawFd; + unsafe { + // A temporary owned file instance + let dfd = std::fs::File::from_raw_fd(self.dfd()); + // So we can call dup() on it + let copy = dfd.try_clone(); + // Now release our temporary ownership of the original + let _ = dfd.into_raw_fd(); + copy + } + } + + /// Borrow the directory file descriptor for this repository. + #[cfg(feature = "cap-std-apis")] + pub fn dfd_borrow<'a>(&'a self) -> io_lifetimes::BorrowedFd<'a> { + unsafe { io_lifetimes::BorrowedFd::borrow_raw_fd(self.dfd()) } + } + + /// Return a new `cap-std` directory reference for this repository. + #[cfg(feature = "cap-std-apis")] + pub fn dfd_as_dir(&self) -> std::io::Result<cap_std::fs::Dir> { + cap_std::fs::Dir::reopen_dir(&self.dfd_borrow()) + } + + /// Find all objects reachable from a commit. + pub fn traverse_commit<P: IsA<gio::Cancellable>>( + &self, + commit_checksum: &str, + maxdepth: i32, + cancellable: Option<&P>, + ) -> Result<HashSet<ObjectName>, Error> { + unsafe { + let mut error = ptr::null_mut(); + let mut hashtable = ptr::null_mut(); + let _ = ffi::ostree_repo_traverse_commit( + self.to_glib_none().0, + commit_checksum.to_glib_none().0, + maxdepth, + &mut hashtable, + cancellable.map(AsRef::as_ref).to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(from_glib_container_variant_set(hashtable)) + } else { + Err(from_glib_full(error)) + } + } + } + + /// List all branch names (refs). + pub fn list_refs<P: IsA<gio::Cancellable>>( + &self, + refspec_prefix: Option<&str>, + cancellable: Option<&P>, + ) -> Result<HashMap<String, String>, Error> { + unsafe { + let mut error = ptr::null_mut(); + let mut hashtable = ptr::null_mut(); + let _ = ffi::ostree_repo_list_refs( + self.to_glib_none().0, + refspec_prefix.to_glib_none().0, + &mut hashtable, + cancellable.map(AsRef::as_ref).to_glib_none().0, + &mut error, + ); + + if error.is_null() { + Ok(FromGlibPtrContainer::from_glib_container(hashtable)) + } else { + Err(from_glib_full(error)) + } + } + } + + /// List all repo objects + pub fn list_objects<P: IsA<gio::Cancellable>>( + &self, + flags: OstreeRepoListObjectsFlags, + cancellable: Option<&P>, + ) -> Result<HashMap<ObjectName, ObjectDetails>, Error> { + unsafe { + let mut error = ptr::null_mut(); + let mut hashtable = ptr::null_mut(); + + ffi::ostree_repo_list_objects( + self.to_glib_none().0, + flags, + &mut hashtable, + cancellable.map(AsRef::as_ref).to_glib_none().0, + &mut error, + ); + + if error.is_null() { + Ok(from_glib_container_variant_map(hashtable)) + } else { + Err(from_glib_full(error)) + } + } + } + + /// List refs with extended options. + #[cfg(any(feature = "v2016_4", feature = "dox"))] + pub fn list_refs_ext<P: IsA<gio::Cancellable>>( + &self, + refspec_prefix: Option<&str>, + flags: RepoListRefsExtFlags, + cancellable: Option<&P>, + ) -> Result<HashMap<String, String>, Error> { + unsafe { + let mut error = ptr::null_mut(); + let mut hashtable = ptr::null_mut(); + let _ = ffi::ostree_repo_list_refs_ext( + self.to_glib_none().0, + refspec_prefix.to_glib_none().0, + &mut hashtable, + flags.into_glib(), + cancellable.map(AsRef::as_ref).to_glib_none().0, + &mut error, + ); + + if error.is_null() { + Ok(FromGlibPtrContainer::from_glib_container(hashtable)) + } else { + Err(from_glib_full(error)) + } + } + } + + /// Resolve a refspec to a commit SHA256. + /// Returns an error if the refspec does not exist. + pub fn require_rev(&self, refspec: &str) -> Result<glib::GString, Error> { + // SAFETY: Since we said `false` for "allow_noent", this function must return a value + Ok(self.resolve_rev(refspec, false)?.unwrap()) + } + + /// Query metadata for a content object. + /// + /// This is similar to [`load_file`], but is more efficient if reading the file content is not needed. + pub fn query_file<P: IsA<gio::Cancellable>>( + &self, + checksum: &str, + cancellable: Option<&P>, + ) -> Result<(gio::FileInfo, glib::Variant), glib::Error> { + unsafe { + let mut out_file_info = ptr::null_mut(); + let mut out_xattrs = ptr::null_mut(); + let mut error = ptr::null_mut(); + let r = ffi::ostree_repo_load_file( + self.to_glib_none().0, + checksum.to_glib_none().0, + ptr::null_mut(), + &mut out_file_info, + &mut out_xattrs, + cancellable.map(|p| p.as_ref()).to_glib_none().0, + &mut error, + ); + if error.is_null() { + debug_assert!(r != 0); + Ok((from_glib_full(out_file_info), from_glib_full(out_xattrs))) + } else { + debug_assert_eq!(r, 0); + Err(from_glib_full(error)) + } + } + } + + /// Write a content object from provided input. + pub fn write_content<P: IsA<gio::InputStream>, Q: IsA<gio::Cancellable>>( + &self, + expected_checksum: Option<&str>, + object_input: &P, + length: u64, + cancellable: Option<&Q>, + ) -> Result<Checksum, Error> { + unsafe { + let mut error = ptr::null_mut(); + let mut out_csum = ptr::null_mut(); + let _ = ffi::ostree_repo_write_content( + self.to_glib_none().0, + expected_checksum.to_glib_none().0, + object_input.as_ref().to_glib_none().0, + length, + &mut out_csum, + cancellable.map(|p| p.as_ref()).to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(from_glib_full(out_csum)) + } else { + Err(from_glib_full(error)) + } + } + } + + /// Write a metadata object. + pub fn write_metadata<P: IsA<gio::Cancellable>>( + &self, + objtype: ObjectType, + expected_checksum: Option<&str>, + object: &glib::Variant, + cancellable: Option<&P>, + ) -> Result<Checksum, Error> { + unsafe { + let mut error = ptr::null_mut(); + let mut out_csum = ptr::null_mut(); + let _ = ffi::ostree_repo_write_metadata( + self.to_glib_none().0, + objtype.into_glib(), + expected_checksum.to_glib_none().0, + object.to_glib_none().0, + &mut out_csum, + cancellable.map(|p| p.as_ref()).to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(from_glib_full(out_csum)) + } else { + Err(from_glib_full(error)) + } + } + } + + /// Asynchronously write a content object. + pub fn write_content_async< + P: IsA<gio::InputStream>, + Q: IsA<gio::Cancellable>, + R: FnOnce(Result<Checksum, Error>) + Send + 'static, + >( + &self, + expected_checksum: Option<&str>, + object: &P, + length: u64, + cancellable: Option<&Q>, + callback: R, + ) { + let user_data: Box<R> = Box::new(callback); + unsafe extern "C" fn write_content_async_trampoline< + R: FnOnce(Result<Checksum, Error>) + Send + 'static, + >( + _source_object: *mut glib::gobject_ffi::GObject, + res: *mut gio::ffi::GAsyncResult, + user_data: glib::ffi::gpointer, + ) { + let mut error = ptr::null_mut(); + let mut out_csum = MaybeUninit::uninit(); + let _ = ffi::ostree_repo_write_content_finish( + _source_object as *mut _, + res, + out_csum.as_mut_ptr(), + &mut error, + ); + let out_csum = out_csum.assume_init(); + let result = if error.is_null() { + Ok(Checksum::from_glib_full(out_csum)) + } else { + Err(from_glib_full(error)) + }; + let callback: Box<R> = Box::from_raw(user_data as *mut _); + callback(result); + } + let callback = write_content_async_trampoline::<R>; + unsafe { + ffi::ostree_repo_write_content_async( + self.to_glib_none().0, + expected_checksum.to_glib_none().0, + object.as_ref().to_glib_none().0, + length, + cancellable.map(|p| p.as_ref()).to_glib_none().0, + Some(callback), + Box::into_raw(user_data) as *mut _, + ); + } + } + + /// Asynchronously write a content object. + pub fn write_content_async_future<P: IsA<gio::InputStream> + Clone + 'static>( + &self, + expected_checksum: Option<&str>, + object: &P, + length: u64, + ) -> Pin<Box<dyn Future<Output = Result<Checksum, Error>> + 'static>> { + let expected_checksum = expected_checksum.map(ToOwned::to_owned); + let object = object.clone(); + Box::pin(gio::GioFuture::new(self, move |obj, cancellable, send| { + obj.write_content_async( + expected_checksum + .as_ref() + .map(::std::borrow::Borrow::borrow), + &object, + length, + Some(cancellable), + move |res| { + send.resolve(res); + }, + ); + })) + } + + /// Asynchronously write a metadata object. + pub fn write_metadata_async< + P: IsA<gio::Cancellable>, + Q: FnOnce(Result<Checksum, Error>) + Send + 'static, + >( + &self, + objtype: ObjectType, + expected_checksum: Option<&str>, + object: &glib::Variant, + cancellable: Option<&P>, + callback: Q, + ) { + let user_data: Box<Q> = Box::new(callback); + unsafe extern "C" fn write_metadata_async_trampoline< + Q: FnOnce(Result<Checksum, Error>) + Send + 'static, + >( + _source_object: *mut glib::gobject_ffi::GObject, + res: *mut gio::ffi::GAsyncResult, + user_data: glib_sys::gpointer, + ) { + let mut error = ptr::null_mut(); + let mut out_csum = MaybeUninit::uninit(); + let _ = ffi::ostree_repo_write_metadata_finish( + _source_object as *mut _, + res, + out_csum.as_mut_ptr(), + &mut error, + ); + let out_csum = out_csum.assume_init(); + let result = if error.is_null() { + Ok(Checksum::from_glib_full(out_csum)) + } else { + Err(from_glib_full(error)) + }; + let callback: Box<Q> = Box::from_raw(user_data as *mut _); + callback(result); + } + let callback = write_metadata_async_trampoline::<Q>; + unsafe { + ffi::ostree_repo_write_metadata_async( + self.to_glib_none().0, + objtype.into_glib(), + expected_checksum.to_glib_none().0, + object.to_glib_none().0, + cancellable.map(|p| p.as_ref()).to_glib_none().0, + Some(callback), + Box::into_raw(user_data) as *mut _, + ); + } + } + + /// Asynchronously write a metadata object. + pub fn write_metadata_async_future( + &self, + objtype: ObjectType, + expected_checksum: Option<&str>, + object: &glib::Variant, + ) -> Pin<Box<dyn Future<Output = Result<Checksum, Error>> + 'static>> { + let expected_checksum = expected_checksum.map(ToOwned::to_owned); + let object = object.clone(); + Box::pin(gio::GioFuture::new(self, move |obj, cancellable, send| { + obj.write_metadata_async( + objtype, + expected_checksum + .as_ref() + .map(::std::borrow::Borrow::borrow), + &object, + Some(cancellable), + move |res| { + send.resolve(res); + }, + ); + })) + } + + /// Load and parse directory metadata. + /// In particular, uid/gid/mode are stored in big-endian format; this function + /// converts them to host native endianness. + pub fn read_dirmeta(&self, checksum: &str) -> Result<crate::DirMetaParsed, glib::Error> { + let v = self.load_variant(crate::ObjectType::DirMeta, checksum)?; + // Safety: We know the variant type will match since we just passed it above + Ok(crate::DirMetaParsed::from_variant(&v).unwrap()) + } +} diff --git a/rust-bindings/src/repo_checkout_at_options/mod.rs b/rust-bindings/src/repo_checkout_at_options/mod.rs new file mode 100644 index 0000000000..9e47017de7 --- /dev/null +++ b/rust-bindings/src/repo_checkout_at_options/mod.rs @@ -0,0 +1,280 @@ +use crate::{RepoCheckoutMode, RepoCheckoutOverwriteMode, RepoDevInoCache, SePolicy}; +use glib::translate::*; +use libc::c_char; +use std::path::PathBuf; + +#[cfg(any(feature = "v2018_2", feature = "dox"))] +mod repo_checkout_filter; +#[cfg(any(feature = "v2018_2", feature = "dox"))] +pub use self::repo_checkout_filter::RepoCheckoutFilter; + +/// Options for checking out an OSTree commit. +pub struct RepoCheckoutAtOptions { + /// Checkout mode. + pub mode: RepoCheckoutMode, + /// Overwrite mode. + pub overwrite_mode: RepoCheckoutOverwriteMode, + /// Deprecated, do not use. + pub enable_uncompressed_cache: bool, + /// Perform `fsync()` on checked out files and directories. + pub enable_fsync: bool, + /// Handle OCI/Docker style whiteout files. + pub process_whiteouts: bool, + /// Require hardlinking. + pub no_copy_fallback: bool, + /// Never hardlink; reflink if possible, otherwise full physical copy. + #[cfg(any(feature = "v2017_6", feature = "dox"))] + pub force_copy: bool, + /// Suppress mode bits outside of 0775 for directories. + #[cfg(any(feature = "v2017_7", feature = "dox"))] + pub bareuseronly_dirs: bool, + /// Copy zero-sized files rather than hardlinking. + #[cfg(any(feature = "v2018_9", feature = "dox"))] + pub force_copy_zerosized: bool, + /// Only check out this subpath. + pub subpath: Option<PathBuf>, + /// A cache from device, inode pairs to checksums. + pub devino_to_csum_cache: Option<RepoDevInoCache>, + /// A callback function to decide which files and directories will be checked out from the + /// repo. See the documentation on [RepoCheckoutFilter](struct.RepoCheckoutFilter.html) for more + /// information on the signature. + /// + /// # Panics + /// This callback may not panic. If it does, `abort()` will be called to avoid unwinding across + /// an FFI boundary and into the libostree C code (which is Undefined Behavior). If you prefer to + /// swallow the panic rather than aborting, you can use `std::panic::catch_unwind` inside your + /// callback to catch and silence any panics that occur. + #[cfg(any(feature = "v2018_2", feature = "dox"))] + pub filter: Option<RepoCheckoutFilter>, + /// SELinux policy. + #[cfg(any(feature = "v2017_6", feature = "dox"))] + pub sepolicy: Option<SePolicy>, + /// When computing security contexts, prefix the path with this value. + pub sepolicy_prefix: Option<String>, +} + +impl Default for RepoCheckoutAtOptions { + fn default() -> Self { + RepoCheckoutAtOptions { + mode: RepoCheckoutMode::None, + overwrite_mode: RepoCheckoutOverwriteMode::None, + enable_uncompressed_cache: false, + enable_fsync: false, + process_whiteouts: false, + no_copy_fallback: false, + #[cfg(feature = "v2017_6")] + force_copy: false, + #[cfg(feature = "v2017_7")] + bareuseronly_dirs: false, + #[cfg(feature = "v2018_9")] + force_copy_zerosized: false, + subpath: None, + devino_to_csum_cache: None, + #[cfg(feature = "v2018_2")] + filter: None, + #[cfg(feature = "v2017_6")] + sepolicy: None, + sepolicy_prefix: None, + } + } +} + +type StringStash<'a, T> = Stash<'a, *const c_char, Option<T>>; +type WrapperStash<'a, GlibT, WrappedT> = Stash<'a, *mut GlibT, Option<WrappedT>>; + +impl<'a> ToGlibPtr<'a, *const ffi::OstreeRepoCheckoutAtOptions> for RepoCheckoutAtOptions { + #[allow(clippy::type_complexity)] + type Storage = ( + Box<ffi::OstreeRepoCheckoutAtOptions>, + StringStash<'a, PathBuf>, + StringStash<'a, String>, + WrapperStash<'a, ffi::OstreeRepoDevInoCache, RepoDevInoCache>, + WrapperStash<'a, ffi::OstreeSePolicy, SePolicy>, + ); + + // We need to make sure that all memory pointed to by the returned pointer is kept alive by + // either the `self` reference or the returned Stash. + fn to_glib_none(&'a self) -> Stash<*const ffi::OstreeRepoCheckoutAtOptions, Self> { + // Creating this struct from zeroed memory is fine since it's `repr(C)` and only contains + // primitive types. In fact, the libostree docs say to zero the struct. This means we handle + // the unused bytes correctly. + // The struct needs to be boxed so the pointer we return remains valid even as the Stash is + // moved around. + let mut options = + Box::new(unsafe { std::mem::zeroed::<ffi::OstreeRepoCheckoutAtOptions>() }); + options.mode = self.mode.into_glib(); + options.overwrite_mode = self.overwrite_mode.into_glib(); + options.enable_uncompressed_cache = self.enable_uncompressed_cache.into_glib(); + options.enable_fsync = self.enable_fsync.into_glib(); + options.process_whiteouts = self.process_whiteouts.into_glib(); + options.no_copy_fallback = self.no_copy_fallback.into_glib(); + + #[cfg(feature = "v2017_6")] + { + options.force_copy = self.force_copy.into_glib(); + } + + #[cfg(feature = "v2017_7")] + { + options.bareuseronly_dirs = self.bareuseronly_dirs.into_glib(); + } + + #[cfg(feature = "v2018_9")] + { + options.force_copy_zerosized = self.force_copy_zerosized.into_glib(); + } + + // We keep these complex values alive by returning them in our Stash. Technically, some of + // these are being kept alive by `self` already, but it's better to be consistent here. + let subpath = self.subpath.to_glib_none(); + options.subpath = subpath.0; + let sepolicy_prefix = self.sepolicy_prefix.to_glib_none(); + options.sepolicy_prefix = sepolicy_prefix.0; + let devino_to_csum_cache = self.devino_to_csum_cache.to_glib_none(); + options.devino_to_csum_cache = devino_to_csum_cache.0; + + #[cfg(feature = "v2017_6")] + let sepolicy = { + let sepolicy = self.sepolicy.to_glib_none(); + options.sepolicy = sepolicy.0; + sepolicy + }; + #[cfg(not(feature = "v2017_6"))] + let sepolicy = None.to_glib_none(); + + #[cfg(feature = "v2018_2")] + { + if let Some(filter) = &self.filter { + options.filter_user_data = filter.to_glib_none().0; + options.filter = Some(repo_checkout_filter::filter_trampoline_unwindsafe); + } + } + + Stash( + options.as_ref(), + ( + options, + subpath, + sepolicy_prefix, + devino_to_csum_cache, + sepolicy, + ), + ) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use glib::ffi::{GFALSE, GTRUE}; + use std::ffi::{CStr, CString}; + use std::ptr; + + #[test] + fn should_convert_default_options() { + let options = RepoCheckoutAtOptions::default(); + let stash = options.to_glib_none(); + let ptr = stash.0; + unsafe { + assert_eq!((*ptr).mode, ffi::OSTREE_REPO_CHECKOUT_MODE_NONE); + assert_eq!( + (*ptr).overwrite_mode, + ffi::OSTREE_REPO_CHECKOUT_OVERWRITE_NONE + ); + assert_eq!((*ptr).enable_uncompressed_cache, GFALSE); + assert_eq!((*ptr).enable_fsync, GFALSE); + assert_eq!((*ptr).process_whiteouts, GFALSE); + assert_eq!((*ptr).no_copy_fallback, GFALSE); + #[cfg(feature = "v2017_6")] + assert_eq!((*ptr).force_copy, GFALSE); + #[cfg(feature = "v2017_7")] + assert_eq!((*ptr).bareuseronly_dirs, GFALSE); + #[cfg(feature = "v2018_9")] + assert_eq!((*ptr).force_copy_zerosized, GFALSE); + assert_eq!((*ptr).unused_bools, [GFALSE; 4]); + assert_eq!((*ptr).subpath, ptr::null()); + assert_eq!((*ptr).devino_to_csum_cache, ptr::null_mut()); + assert_eq!((*ptr).unused_ints, [0; 6]); + assert_eq!((*ptr).unused_ptrs, [ptr::null_mut(); 3]); + #[cfg(feature = "v2018_2")] + assert_eq!((*ptr).filter, None); + #[cfg(feature = "v2018_2")] + assert_eq!((*ptr).filter_user_data, ptr::null_mut()); + #[cfg(feature = "v2017_6")] + assert_eq!((*ptr).sepolicy, ptr::null_mut()); + assert_eq!((*ptr).sepolicy_prefix, ptr::null()); + } + } + + #[test] + fn should_convert_non_default_options() { + let options = RepoCheckoutAtOptions { + mode: RepoCheckoutMode::User, + overwrite_mode: RepoCheckoutOverwriteMode::UnionIdentical, + enable_uncompressed_cache: true, + enable_fsync: true, + process_whiteouts: true, + no_copy_fallback: true, + #[cfg(feature = "v2017_6")] + force_copy: true, + #[cfg(feature = "v2017_7")] + bareuseronly_dirs: true, + #[cfg(feature = "v2018_9")] + force_copy_zerosized: true, + subpath: Some("sub/path".into()), + devino_to_csum_cache: Some(RepoDevInoCache::new()), + #[cfg(feature = "v2018_2")] + filter: RepoCheckoutFilter::new(|_repo, _path, _stat| { + crate::RepoCheckoutFilterResult::Skip + }), + #[cfg(feature = "v2017_6")] + sepolicy: Some( + SePolicy::new(&gio::File::for_path("a/b"), gio::NONE_CANCELLABLE).unwrap(), + ), + sepolicy_prefix: Some("prefix".into()), + }; + let stash = options.to_glib_none(); + let ptr = stash.0; + unsafe { + assert_eq!((*ptr).mode, ffi::OSTREE_REPO_CHECKOUT_MODE_USER); + assert_eq!( + (*ptr).overwrite_mode, + ffi::OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_IDENTICAL + ); + assert_eq!((*ptr).enable_uncompressed_cache, GTRUE); + assert_eq!((*ptr).enable_fsync, GTRUE); + assert_eq!((*ptr).process_whiteouts, GTRUE); + assert_eq!((*ptr).no_copy_fallback, GTRUE); + #[cfg(feature = "v2017_6")] + assert_eq!((*ptr).force_copy, GTRUE); + #[cfg(feature = "v2017_7")] + assert_eq!((*ptr).bareuseronly_dirs, GTRUE); + #[cfg(feature = "v2018_9")] + assert_eq!((*ptr).force_copy_zerosized, GTRUE); + assert_eq!((*ptr).unused_bools, [GFALSE; 4]); + assert_eq!( + CStr::from_ptr((*ptr).subpath), + CString::new("sub/path").unwrap().as_c_str() + ); + assert_eq!( + (*ptr).devino_to_csum_cache, + options.devino_to_csum_cache.to_glib_none().0 + ); + assert_eq!((*ptr).unused_ints, [0; 6]); + assert_eq!((*ptr).unused_ptrs, [ptr::null_mut(); 3]); + #[cfg(feature = "v2018_2")] + assert!((*ptr).filter == Some(repo_checkout_filter::filter_trampoline_unwindsafe)); + #[cfg(feature = "v2018_2")] + assert_eq!( + (*ptr).filter_user_data, + options.filter.as_ref().unwrap().to_glib_none().0, + ); + #[cfg(feature = "v2017_6")] + assert_eq!((*ptr).sepolicy, options.sepolicy.to_glib_none().0); + assert_eq!( + CStr::from_ptr((*ptr).sepolicy_prefix), + CString::new("prefix").unwrap().as_c_str() + ); + } + } +} diff --git a/rust-bindings/src/repo_checkout_at_options/repo_checkout_filter.rs b/rust-bindings/src/repo_checkout_at_options/repo_checkout_filter.rs new file mode 100644 index 0000000000..17310e4216 --- /dev/null +++ b/rust-bindings/src/repo_checkout_at_options/repo_checkout_filter.rs @@ -0,0 +1,217 @@ +use crate::{Repo, RepoCheckoutFilterResult}; +use glib::ffi::gpointer; +use glib::translate::*; +use libc::c_char; +use std::any::Any; +use std::panic::catch_unwind; +use std::path::{Path, PathBuf}; +use std::process::abort; + +/// A filter callback to decide which files to checkout from a [Repo](struct.Repo.html). The +/// function is called for every directory and file in the dirtree. +/// +/// # Arguments +/// * `repo` - the `Repo` that is being checked out +/// * `path` - the path of the current file, as an absolute path rooted at the commit's root. The +/// root directory is '/', a subdir would be '/subdir' etc. +/// * `stat` - the metadata of the current file +/// +/// # Return Value +/// The return value determines whether the current file is checked out or skipped. +pub struct RepoCheckoutFilter(Box<dyn Fn(&Repo, &Path, &libc::stat) -> RepoCheckoutFilterResult>); + +impl RepoCheckoutFilter { + /// Wrap a closure for use as a filter function. + /// + /// # Return Value + /// The return value is always `Some` containing the value. It simply comes pre-wrapped for your + /// convenience. + pub fn new<F>(closure: F) -> Option<RepoCheckoutFilter> + where + F: (Fn(&Repo, &Path, &libc::stat) -> RepoCheckoutFilterResult) + 'static, + { + Some(RepoCheckoutFilter(Box::new(closure))) + } + + /// Call the contained closure. + fn call(&self, repo: &Repo, path: &Path, stat: &libc::stat) -> RepoCheckoutFilterResult { + self.0(repo, path, stat) + } +} + +impl<'a> ToGlibPtr<'a, gpointer> for RepoCheckoutFilter { + type Storage = (); + + fn to_glib_none(&'a self) -> Stash<gpointer, Self> { + Stash(self as *const RepoCheckoutFilter as gpointer, ()) + } +} + +impl FromGlibPtrNone<gpointer> for &RepoCheckoutFilter { + // `ptr` must be valid for the lifetime of the returned reference. + unsafe fn from_glib_none(ptr: gpointer) -> Self { + assert!(!ptr.is_null()); + &*(ptr as *const RepoCheckoutFilter) + } +} + +/// Trampoline to be called by libostree that calls the Rust closure in the `user_data` parameter. +/// +/// # Safety +/// All parameters must be valid pointers for the runtime of the function. In particular, +/// `user_data` must point to a [RepoCheckoutFilter](struct.RepoCheckoutFilter.html) value. +/// +/// # Panics +/// If any parameter is a null pointer, the function panics. +unsafe fn filter_trampoline( + repo: *mut ffi::OstreeRepo, + path: *const c_char, + stat: *mut libc::stat, + user_data: gpointer, +) -> ffi::OstreeRepoCheckoutFilterResult { + // We can't guarantee it's a valid pointer, but we can make sure it's not null. + assert!(!stat.is_null()); + let stat = &*stat; + // This reference is valid until the end of this function, which is shorter than the lifetime + // of `user_data` so we're fine. + let closure: &RepoCheckoutFilter = from_glib_none(user_data); + // `repo` lives at least until the end of this function. This means we can just borrow the + // reference so long as our `repo` is not moved out of this function. + let repo = from_glib_borrow(repo); + // This is a copy so no problems here. + let path: PathBuf = from_glib_none(path); + + let result = closure.call(&repo, &path, stat); + result.into_glib() +} + +/// Unwind-safe trampoline to call the Rust filter callback. See [filter_trampoline](fn.filter_trampoline.html). +/// This function additionally catches panics and aborts to avoid unwinding into C code. +pub(super) unsafe extern "C" fn filter_trampoline_unwindsafe( + repo: *mut ffi::OstreeRepo, + path: *const c_char, + stat: *mut libc::stat, + user_data: gpointer, +) -> ffi::OstreeRepoCheckoutFilterResult { + // Unwinding across an FFI boundary is Undefined Behavior and we have no other way to communicate + // the error. We abort() safely to avoid further problems. + let result = catch_unwind(move || filter_trampoline(repo, path, stat, user_data)); + result.unwrap_or_else(|panic| { + print_panic(panic); + abort() + }) +} + +/// Print a panic message and the value to stderr, if we can. +/// +/// If the panic value is either `&str` or `String`, we print it. Otherwise, we don't. +fn print_panic(panic: Box<dyn Any>) { + eprintln!("A Rust callback invoked by C code panicked."); + eprintln!("Unwinding across FFI boundaries is Undefined Behavior so abort() will be called."); + let msg = { + if let Some(s) = panic.as_ref().downcast_ref::<&str>() { + s + } else if let Some(s) = panic.as_ref().downcast_ref::<String>() { + s + } else { + "UNABLE TO SHOW VALUE OF PANIC" + } + }; + eprintln!("Panic value: {}", msg); +} + +#[cfg(test)] +mod tests { + use super::*; + use std::ffi::CString; + use std::ptr; + + #[test] + #[should_panic] + fn trampoline_should_panic_if_repo_is_nullptr() { + let path = CString::new("/a/b/c").unwrap(); + let mut stat: libc::stat = unsafe { std::mem::zeroed() }; + let filter = RepoCheckoutFilter(Box::new(|_, _, _| RepoCheckoutFilterResult::Allow)); + unsafe { + filter_trampoline( + ptr::null_mut(), + path.as_ptr(), + &mut stat, + filter.to_glib_none().0, + ); + } + } + + #[test] + #[should_panic] + fn trampoline_should_panic_if_path_is_nullptr() { + let repo = Repo::new_default(); + let mut stat: libc::stat = unsafe { std::mem::zeroed() }; + let filter = RepoCheckoutFilter(Box::new(|_, _, _| RepoCheckoutFilterResult::Allow)); + unsafe { + filter_trampoline( + repo.to_glib_none().0, + ptr::null(), + &mut stat, + filter.to_glib_none().0, + ); + } + } + + #[test] + #[should_panic] + fn trampoline_should_panic_if_stat_is_nullptr() { + let repo = Repo::new_default(); + let path = CString::new("/a/b/c").unwrap(); + let filter = RepoCheckoutFilter(Box::new(|_, _, _| RepoCheckoutFilterResult::Allow)); + unsafe { + filter_trampoline( + repo.to_glib_none().0, + path.as_ptr(), + ptr::null_mut(), + filter.to_glib_none().0, + ); + } + } + + #[test] + #[should_panic] + fn trampoline_should_panic_if_user_data_is_nullptr() { + let repo = Repo::new_default(); + let path = CString::new("/a/b/c").unwrap(); + let mut stat: libc::stat = unsafe { std::mem::zeroed() }; + unsafe { + filter_trampoline( + repo.to_glib_none().0, + path.as_ptr(), + &mut stat, + ptr::null_mut(), + ); + } + } + + #[test] + fn trampoline_should_call_the_closure() { + let repo = Repo::new_default(); + let path = CString::new("/a/b/c").unwrap(); + let mut stat: libc::stat = unsafe { std::mem::zeroed() }; + let filter = { + let repo = repo.clone(); + let path = path.clone(); + RepoCheckoutFilter(Box::new(move |arg_repo, arg_path, _| { + assert_eq!(arg_repo, &repo); + assert_eq!(&CString::new(arg_path.to_str().unwrap()).unwrap(), &path); + RepoCheckoutFilterResult::Skip + })) + }; + let result = unsafe { + filter_trampoline( + repo.to_glib_none().0, + path.as_ptr(), + &mut stat, + filter.to_glib_none().0, + ) + }; + assert_eq!(result, ffi::OSTREE_REPO_CHECKOUT_FILTER_SKIP); + } +} diff --git a/rust-bindings/src/repo_transaction_stats.rs b/rust-bindings/src/repo_transaction_stats.rs new file mode 100644 index 0000000000..1d12531b75 --- /dev/null +++ b/rust-bindings/src/repo_transaction_stats.rs @@ -0,0 +1,45 @@ +glib::wrapper! { + /// A list of statistics for each transaction that may be interesting for reporting purposes. + #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] + pub struct RepoTransactionStats(Boxed<ffi::OstreeRepoTransactionStats>); + + match fn { + copy => |ptr| glib::gobject_ffi::g_boxed_copy(ffi::ostree_repo_transaction_stats_get_type(), ptr as *mut _) as *mut ffi::OstreeRepoTransactionStats, + free => |ptr| glib::gobject_ffi::g_boxed_free(ffi::ostree_repo_transaction_stats_get_type(), ptr as *mut _), + init => |_ptr| (), + clear => |_ptr| (), + type_ => || ffi::ostree_repo_transaction_stats_get_type(), + } +} + +impl RepoTransactionStats { + /// The total number of metadata objects in the repository after this transaction has completed. + pub fn get_metadata_objects_total(&self) -> usize { + self.0.metadata_objects_total as usize + } + + /// The number of metadata objects that were written to the repository in this transaction. + pub fn get_metadata_objects_written(&self) -> usize { + self.0.metadata_objects_written as usize + } + + /// The total number of content objects in the repository after this transaction has completed. + pub fn get_content_objects_total(&self) -> usize { + self.0.content_objects_total as usize + } + + /// The number of content objects that were written to the repository in this transaction. + pub fn get_content_objects_written(&self) -> usize { + self.0.content_objects_written as usize + } + + /// The amount of data added to the repository, in bytes, counting only content objects. + pub fn get_content_bytes_written(&self) -> u64 { + self.0.content_bytes_written + } + + /// The amount of cache hits during this transaction. + pub fn get_devino_cache_hits(&self) -> usize { + self.0.devino_cache_hits as usize + } +} diff --git a/rust-bindings/src/se_policy.rs b/rust-bindings/src/se_policy.rs new file mode 100644 index 0000000000..43f8c11fac --- /dev/null +++ b/rust-bindings/src/se_policy.rs @@ -0,0 +1,11 @@ +use crate::SePolicy; +use std::ptr; + +impl SePolicy { + /// Reset the SELinux filesystem creation context. + pub fn fscreatecon_cleanup() { + unsafe { + ffi::ostree_sepolicy_fscreatecon_cleanup(ptr::null_mut()); + } + } +} diff --git a/rust-bindings/src/sysroot.rs b/rust-bindings/src/sysroot.rs new file mode 100644 index 0000000000..5255c28627 --- /dev/null +++ b/rust-bindings/src/sysroot.rs @@ -0,0 +1,107 @@ +use crate::gio; +use crate::Sysroot; +use std::path::PathBuf; + +#[derive(Clone, Debug, Default)] +/// Builder object for `Sysroot`. +pub struct SysrootBuilder { + path: Option<PathBuf>, + mount_namespace_in_use: bool, +} + +impl SysrootBuilder { + /// Create a new builder for `Sysroot`. + pub fn new() -> Self { + Self::default() + } + + /// Set the path to the sysroot location. + pub fn path(mut self, path: Option<PathBuf>) -> Self { + self.path = path; + self + } + + #[cfg(any(feature = "v2020_1", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_1")))] + /// Set whether the logic is running in its own mount namespace. + pub fn mount_namespace_in_use(mut self, mount_namespace_in_use: bool) -> Self { + self.mount_namespace_in_use = mount_namespace_in_use; + self + } + + /// Load an existing `Sysroot` from disk, finalizing this builder. + pub fn load(self, cancellable: Option<&gio::Cancellable>) -> Result<Sysroot, glib::Error> { + let sysroot = self.configure_common(); + sysroot.load(cancellable)?; + + Ok(sysroot) + } + + /// Create a new `Sysroot` on disk, finalizing this builder. + pub fn create(self, cancellable: Option<&gio::Cancellable>) -> Result<Sysroot, glib::Error> { + let sysroot = self.configure_common(); + sysroot.ensure_initialized(cancellable)?; + sysroot.load(cancellable)?; + + Ok(sysroot) + } + + /// Perform common configuration steps, returning a not-yet-fully-loaded `Sysroot`. + fn configure_common(self) -> Sysroot { + let sysroot = { + let opt_file = self.path.map(gio::File::for_path); + Sysroot::new(opt_file.as_ref()) + }; + + #[cfg(feature = "v2020_1")] + if self.mount_namespace_in_use { + sysroot.set_mount_namespace_in_use(); + } + + sysroot + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_sysroot_create_load_empty() { + // Create and load an empty sysroot. Make sure it can be properly + // inspected as empty, without panics. + let tmpdir = tempfile::tempdir().unwrap(); + + let path_created = { + let tmp_path = Some(tmpdir.path().to_path_buf()); + let builder = SysrootBuilder::new().path(tmp_path); + + let sysroot = builder.create(gio::NONE_CANCELLABLE).unwrap(); + + assert!(sysroot.fd() >= 0); + assert_eq!(sysroot.deployments().len(), 0); + assert_eq!(sysroot.booted_deployment(), None); + assert_eq!(sysroot.bootversion(), 0); + assert_eq!(sysroot.subbootversion(), 0); + sysroot.cleanup(gio::NONE_CANCELLABLE).unwrap(); + + sysroot.path().unwrap() + }; + let path_loaded = { + let tmp_path = Some(tmpdir.path().to_path_buf()); + let builder = SysrootBuilder::new().path(tmp_path); + + let sysroot = builder.create(gio::NONE_CANCELLABLE).unwrap(); + + assert!(sysroot.fd() >= 0); + assert_eq!(sysroot.deployments().len(), 0); + assert_eq!(sysroot.booted_deployment(), None); + assert_eq!(sysroot.bootversion(), 0); + assert_eq!(sysroot.subbootversion(), 0); + sysroot.cleanup(gio::NONE_CANCELLABLE).unwrap(); + + sysroot.path().unwrap() + }; + assert_eq!(path_created.to_string(), path_loaded.to_string()); + } +} diff --git a/rust-bindings/src/sysroot_deploy_tree_opts.rs b/rust-bindings/src/sysroot_deploy_tree_opts.rs new file mode 100644 index 0000000000..62376f76eb --- /dev/null +++ b/rust-bindings/src/sysroot_deploy_tree_opts.rs @@ -0,0 +1,101 @@ +use ffi::OstreeSysrootDeployTreeOpts; +use glib::translate::*; +use libc::c_char; + +/// Options for deploying an ostree commit. +pub struct SysrootDeployTreeOpts<'a> { + /// Use these kernel arguments. + pub override_kernel_argv: Option<&'a [&'a str]>, + /// Paths to initramfs files to overlay. + pub overlay_initrds: Option<&'a [&'a str]>, +} + +impl<'a> Default for SysrootDeployTreeOpts<'a> { + fn default() -> Self { + SysrootDeployTreeOpts { + override_kernel_argv: None, + overlay_initrds: None, + } + } +} + +type OptionStrSliceStorage<'a> = + <Option<&'a [&'a str]> as ToGlibPtr<'a, *mut *mut c_char>>::Storage; + +impl<'a, 'b: 'a> ToGlibPtr<'a, *const OstreeSysrootDeployTreeOpts> for SysrootDeployTreeOpts<'b> { + type Storage = ( + Box<OstreeSysrootDeployTreeOpts>, + OptionStrSliceStorage<'a>, + OptionStrSliceStorage<'a>, + ); + + fn to_glib_none(&'a self) -> Stash<*const OstreeSysrootDeployTreeOpts, Self> { + // Creating this struct from zeroed memory is fine since it's `repr(C)` and only contains + // primitive types. Zeroing it ensures we handle the unused bytes correctly. + // The struct needs to be boxed so the pointer we return remains valid even as the Stash is + // moved around. + let mut options = Box::new(unsafe { std::mem::zeroed::<OstreeSysrootDeployTreeOpts>() }); + let override_kernel_argv = self.override_kernel_argv.to_glib_none(); + let overlay_initrds = self.overlay_initrds.to_glib_none(); + options.override_kernel_argv = override_kernel_argv.0; + options.overlay_initrds = overlay_initrds.0; + Stash( + options.as_ref(), + (options, override_kernel_argv.1, overlay_initrds.1), + ) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use std::{ffi::CStr, ptr::null_mut}; + + unsafe fn ptr_array_to_slice<'a, T>(ptr: *mut *mut T) -> &'a [*mut T] { + let mut len = 0; + while !(*ptr.offset(len)).is_null() { + len += 1; + } + std::slice::from_raw_parts(ptr, len as usize) + } + + unsafe fn str_ptr_array_to_vec<'a>(ptr: *mut *mut c_char) -> Vec<&'a str> { + ptr_array_to_slice(ptr) + .iter() + .map(|x| CStr::from_ptr(*x).to_str().unwrap()) + .collect() + } + + #[test] + fn should_convert_default_options() { + let options = SysrootDeployTreeOpts::default(); + let stash = options.to_glib_none(); + let ptr = stash.0; + unsafe { + assert_eq!((*ptr).override_kernel_argv, null_mut()); + assert_eq!((*ptr).overlay_initrds, null_mut()); + } + } + + #[test] + fn should_convert_non_default_options() { + let override_kernel_argv = vec!["quiet", "splash", "ro"]; + let overlay_initrds = vec!["overlay1", "overlay2"]; + let options = SysrootDeployTreeOpts { + override_kernel_argv: Some(&override_kernel_argv), + overlay_initrds: Some(&overlay_initrds), + }; + let stash = options.to_glib_none(); + let ptr = stash.0; + unsafe { + assert_eq!( + str_ptr_array_to_vec((*ptr).override_kernel_argv), + vec!["quiet", "splash", "ro"] + ); + assert_eq!( + str_ptr_array_to_vec((*ptr).overlay_initrds), + vec!["overlay1", "overlay2"] + ); + } + } +} diff --git a/rust-bindings/src/sysroot_write_deployments_opts.rs b/rust-bindings/src/sysroot_write_deployments_opts.rs new file mode 100644 index 0000000000..81c436c338 --- /dev/null +++ b/rust-bindings/src/sysroot_write_deployments_opts.rs @@ -0,0 +1,57 @@ +use ffi::OstreeSysrootWriteDeploymentsOpts; +use glib::translate::*; + +/// Options for writing a deployment. +pub struct SysrootWriteDeploymentsOpts { + /// Perform cleanup after writing the deployment. + pub do_postclean: bool, +} + +impl Default for SysrootWriteDeploymentsOpts { + fn default() -> Self { + SysrootWriteDeploymentsOpts { + do_postclean: false, + } + } +} + +impl<'a> ToGlibPtr<'a, *const OstreeSysrootWriteDeploymentsOpts> for SysrootWriteDeploymentsOpts { + type Storage = Box<OstreeSysrootWriteDeploymentsOpts>; + + fn to_glib_none(&'a self) -> Stash<*const OstreeSysrootWriteDeploymentsOpts, Self> { + // Creating this struct from zeroed memory is fine since it's `repr(C)` and only contains + // primitive types. + // The struct needs to be boxed so the pointer we return remains valid even as the Stash is + // moved around. + let mut options = + Box::new(unsafe { std::mem::zeroed::<OstreeSysrootWriteDeploymentsOpts>() }); + options.do_postclean = self.do_postclean.into_glib(); + Stash(options.as_ref(), options) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use glib::ffi::{GFALSE, GTRUE}; + + #[test] + fn should_convert_default_options() { + let options = SysrootWriteDeploymentsOpts::default(); + let stash = options.to_glib_none(); + let ptr = stash.0; + unsafe { + assert_eq!((*ptr).do_postclean, GFALSE); + } + } + + #[test] + fn should_convert_non_default_options() { + let options = SysrootWriteDeploymentsOpts { do_postclean: true }; + let stash = options.to_glib_none(); + let ptr = stash.0; + unsafe { + assert_eq!((*ptr).do_postclean, GTRUE); + } + } +} diff --git a/rust-bindings/src/tests/collection_ref.rs b/rust-bindings/src/tests/collection_ref.rs new file mode 100644 index 0000000000..b6bf050e6b --- /dev/null +++ b/rust-bindings/src/tests/collection_ref.rs @@ -0,0 +1,79 @@ +#![cfg(feature = "v2018_6")] + +use crate::CollectionRef; +use std::collections::hash_map::DefaultHasher; +use std::hash::{Hash, Hasher}; + +fn hash(v: &impl Hash) -> u64 { + let mut s = DefaultHasher::new(); + v.hash(&mut s); + s.finish() +} + +#[test] +fn same_value_should_be_equal() { + let r = CollectionRef::new(Some("io.gitlab.fkrull"), "ref").unwrap(); + assert_eq!(r, r); +} + +#[test] +fn equal_values_should_be_equal() { + let a = CollectionRef::new(Some("io.gitlab.fkrull"), "ref").unwrap(); + let b = CollectionRef::new(Some("io.gitlab.fkrull"), "ref").unwrap(); + assert_eq!(a, b); +} + +#[test] +fn equal_values_without_collection_id_should_be_equal() { + let a = CollectionRef::new(None, "ref-name").unwrap(); + let b = CollectionRef::new(None, "ref-name").unwrap(); + assert_eq!(a, b); +} + +#[test] +fn different_values_should_not_be_equal() { + let a = CollectionRef::new(Some("io.gitlab.fkrull"), "ref1").unwrap(); + let b = CollectionRef::new(Some("io.gitlab.fkrull"), "ref2").unwrap(); + assert_ne!(a, b); +} + +#[test] +fn new_with_invalid_collection_id_should_return_none() { + let r = CollectionRef::new(Some(".abc"), "ref"); + assert_eq!(r, None); +} + +#[test] +fn hash_for_equal_values_should_be_equal() { + let a = CollectionRef::new(Some("io.gitlab.fkrull"), "ref").unwrap(); + let b = CollectionRef::new(Some("io.gitlab.fkrull"), "ref").unwrap(); + assert_eq!(hash(&a), hash(&b)); +} + +#[test] +fn hash_for_values_with_different_collection_id_should_be_different() { + let a = CollectionRef::new(Some("io.gitlab.fkrull1"), "ref").unwrap(); + let b = CollectionRef::new(Some("io.gitlab.fkrull2"), "ref").unwrap(); + assert_ne!(hash(&a), hash(&b)); +} + +#[test] +fn hash_for_values_with_different_ref_id_should_be_different() { + let a = CollectionRef::new(Some("io.gitlab.fkrull"), "ref-1").unwrap(); + let b = CollectionRef::new(Some("io.gitlab.fkrull"), "ref-2").unwrap(); + assert_ne!(hash(&a), hash(&b)); +} + +#[test] +fn hash_should_be_different_if_collection_id_is_absent() { + let a = CollectionRef::new(Some("io.gitlab.fkrull"), "ref").unwrap(); + let b = CollectionRef::new(None, "ref").unwrap(); + assert_ne!(hash(&a), hash(&b)); +} + +#[test] +fn clone_should_be_equal_to_original_value() { + let a = CollectionRef::new(Some("io.gitlab.fkrull"), "ref").unwrap(); + let b = a.clone(); + assert_eq!(a, b); +} diff --git a/rust-bindings/src/tests/kernel_args.rs b/rust-bindings/src/tests/kernel_args.rs new file mode 100644 index 0000000000..c8f9e6256b --- /dev/null +++ b/rust-bindings/src/tests/kernel_args.rs @@ -0,0 +1,64 @@ +#![cfg(feature = "v2019_3")] + +use crate::KernelArgs; + +#[test] +fn should_create_and_fill_kernel_args() { + let mut args = KernelArgs::new(); + args.append("key=value"); + args.append("arg1"); + args.append("key2=value2"); + assert_eq!(args.to_string(), "key=value arg1 key2=value2"); +} + +#[test] +fn should_convert_to_string_vec() { + let mut args = KernelArgs::new(); + args.parse_append("key=value arg1 key2=value2"); + assert_eq!( + args.to_strv() + .iter() + .map(|s| s.as_str()) + .collect::<Vec<_>>(), + vec!["key=value", "arg1", "key2=value2"] + ); +} + +#[test] +fn should_get_last_value() { + let mut args = KernelArgs::new(); + args.append("key=value1"); + args.append("key=value2"); + args.append("key=value3"); + assert_eq!(args.get_last_value("key").unwrap(), "value3"); +} + +#[test] +fn should_convert_from_string() { + let args = KernelArgs::from(String::from("arg1 arg2 arg3=value")); + assert_eq!(args.to_strv(), vec!["arg1", "arg2", "arg3=value"]); +} + +#[test] +fn should_append_argv() { + let mut args = KernelArgs::new(); + args.append_argv(&["arg1", "arg2=value", "arg3", "arg4=value"]); + assert_eq!(args.to_string(), "arg1 arg2=value arg3 arg4=value"); +} + +#[test] +fn should_append_argv_filtered() { + let mut args = KernelArgs::new(); + args.append_argv_filtered( + &["prefix.arg1", "arg2", "prefix.arg3", "arg4=value"], + &["prefix"], + ); + assert_eq!(args.to_string(), "arg2 arg4=value"); +} + +#[test] +fn should_replace_argv() { + let mut args = KernelArgs::from_string("arg1=value1 arg2=value2 arg3"); + args.replace_argv(&["arg1=value3", "arg3=value4", "arg4"]); + assert_eq!(args.to_string(), "arg1=value3 arg2=value2 arg3=value4 arg4"); +} diff --git a/rust-bindings/src/tests/mod.rs b/rust-bindings/src/tests/mod.rs new file mode 100644 index 0000000000..ca79e91597 --- /dev/null +++ b/rust-bindings/src/tests/mod.rs @@ -0,0 +1,3 @@ +mod collection_ref; +mod kernel_args; +mod repo; diff --git a/rust-bindings/src/tests/repo.rs b/rust-bindings/src/tests/repo.rs new file mode 100644 index 0000000000..59a6792db1 --- /dev/null +++ b/rust-bindings/src/tests/repo.rs @@ -0,0 +1,14 @@ +use crate::Repo; +use crate::RepoMode; + +#[test] +fn should_get_repo_mode_from_string() { + let mode = Repo::mode_from_string("archive").unwrap(); + assert_eq!(RepoMode::Archive, mode); +} + +#[test] +fn should_return_error_for_invalid_repo_mode_string() { + let result = Repo::mode_from_string("invalid-repo-mode"); + assert!(result.is_err()); +} diff --git a/rust-bindings/sys/Cargo.toml b/rust-bindings/sys/Cargo.toml new file mode 100644 index 0000000000..5bda7ba37d --- /dev/null +++ b/rust-bindings/sys/Cargo.toml @@ -0,0 +1,209 @@ +[build-dependencies] +system-deps = "3" + +[dependencies] +glib-sys = "0.14" +gobject-sys = "0.14" +gio-sys = "0.14" +libc = "0.2" + +[dev-dependencies] +shell-words = "1.0.0" +tempfile = "3" + +[features] +v2014_9 = [] +v2015_7 = ["v2014_9"] +v2016_3 = ["v2015_7"] +v2016_4 = ["v2016_3"] +v2016_5 = ["v2016_4"] +v2016_6 = ["v2016_5"] +v2016_7 = ["v2016_6"] +v2016_8 = ["v2016_7"] +v2016_14 = ["v2016_8"] +v2017_1 = ["v2016_14"] +v2017_2 = ["v2017_1"] +v2017_3 = ["v2017_2"] +v2017_4 = ["v2017_3"] +v2017_6 = ["v2017_4"] +v2017_7 = ["v2017_6"] +v2017_8 = ["v2017_7"] +v2017_9 = ["v2017_8"] +v2017_10 = ["v2017_9"] +v2017_11 = ["v2017_10"] +v2017_12 = ["v2017_11"] +v2017_13 = ["v2017_12"] +v2017_15 = ["v2017_13"] +v2018_2 = ["v2017_15"] +v2018_3 = ["v2018_2"] +v2018_5 = ["v2018_3"] +v2018_6 = ["v2018_5"] +v2018_7 = ["v2018_6"] +v2018_9 = ["v2018_7"] +v2019_2 = ["v2018_9"] +v2019_3 = ["v2019_2"] +v2019_4 = ["v2019_3"] +v2019_6 = ["v2019_4"] +v2020_1 = ["v2019_6"] +v2020_2 = ["v2020_1"] +v2020_4 = ["v2020_2"] +dox = [] +v2020_7 = ["v2020_4"] +v2020_8 = ["v2020_7"] +v2021_1 = ["v2020_8"] +v2021_2 = ["v2021_1"] +v2021_3 = ["v2021_2"] +v2021_4 = ["v2021_3"] +v2021_5 = ["v2021_4"] +v2022_2 = ["v2021_5"] + +[lib] +name = "ostree_sys" + +[package] +authors = ["Felix Krull"] +build = "build.rs" +categories = ["external-ffi-bindings"] +description = "FFI bindings to libostree-1" +documentation = "https://docs.rs/ostree-sys" +keywords = ["ffi", "ostree", "libostree"] +license = "MIT" +links = "ostree-1" +name = "ostree-sys" +repository = "https://github.com/ostreedev/ostree-rs" +version = "0.9.2" +edition = "2018" +[package.metadata.docs.rs] +features = ["dox"] +[package.metadata.system-deps.ostree_1] +name = "ostree-1" +version = "0.0" + +[package.metadata.system-deps.ostree_1.v2014_9] +version = "2014.9" + +[package.metadata.system-deps.ostree_1.v2015_7] +version = "2015.7" + +[package.metadata.system-deps.ostree_1.v2016_3] +version = "2016.3" + +[package.metadata.system-deps.ostree_1.v2016_4] +version = "2016.4" + +[package.metadata.system-deps.ostree_1.v2016_5] +version = "2016.5" + +[package.metadata.system-deps.ostree_1.v2016_6] +version = "2016.6" + +[package.metadata.system-deps.ostree_1.v2016_7] +version = "2016.7" + +[package.metadata.system-deps.ostree_1.v2016_8] +version = "2016.8" + +[package.metadata.system-deps.ostree_1.v2016_14] +version = "2016.14" + +[package.metadata.system-deps.ostree_1.v2017_1] +version = "2017.1" + +[package.metadata.system-deps.ostree_1.v2017_2] +version = "2017.2" + +[package.metadata.system-deps.ostree_1.v2017_3] +version = "2017.3" + +[package.metadata.system-deps.ostree_1.v2017_4] +version = "2017.4" + +[package.metadata.system-deps.ostree_1.v2017_6] +version = "2017.6" + +[package.metadata.system-deps.ostree_1.v2017_7] +version = "2017.7" + +[package.metadata.system-deps.ostree_1.v2017_8] +version = "2017.8" + +[package.metadata.system-deps.ostree_1.v2017_9] +version = "2017.9" + +[package.metadata.system-deps.ostree_1.v2017_10] +version = "2017.10" + +[package.metadata.system-deps.ostree_1.v2017_11] +version = "2017.11" + +[package.metadata.system-deps.ostree_1.v2017_12] +version = "2017.12" + +[package.metadata.system-deps.ostree_1.v2017_13] +version = "2017.13" + +[package.metadata.system-deps.ostree_1.v2017_15] +version = "2017.15" + +[package.metadata.system-deps.ostree_1.v2018_2] +version = "2018.2" + +[package.metadata.system-deps.ostree_1.v2018_3] +version = "2018.3" + +[package.metadata.system-deps.ostree_1.v2018_5] +version = "2018.5" + +[package.metadata.system-deps.ostree_1.v2018_6] +version = "2018.6" + +[package.metadata.system-deps.ostree_1.v2018_7] +version = "2018.7" + +[package.metadata.system-deps.ostree_1.v2018_9] +version = "2018.9" + +[package.metadata.system-deps.ostree_1.v2019_2] +version = "2019.2" + +[package.metadata.system-deps.ostree_1.v2019_3] +version = "2019.3" + +[package.metadata.system-deps.ostree_1.v2019_4] +version = "2019.4" + +[package.metadata.system-deps.ostree_1.v2019_6] +version = "2019.6" + +[package.metadata.system-deps.ostree_1.v2020_1] +version = "2020.1" + +[package.metadata.system-deps.ostree_1.v2020_2] +version = "2020.2" + +[package.metadata.system-deps.ostree_1.v2020_4] +version = "2020.4" + +[package.metadata.system-deps.ostree_1.v2020_7] +version = "2020.7" + +[package.metadata.system-deps.ostree_1.v2020_8] +version = "2020.8" + +[package.metadata.system-deps.ostree_1.v2021_1] +version = "2021.1" + +[package.metadata.system-deps.ostree_1.v2021_2] +version = "2021.2" + +[package.metadata.system-deps.ostree_1.v2021_3] +version = "2021.3" + +[package.metadata.system-deps.ostree_1.v2021_4] +version = "2021.4" + +[package.metadata.system-deps.ostree_1.v2021_5] +version = "2021.5" + +[package.metadata.system-deps.ostree_1.v2022_2] +version = "2022.2" diff --git a/rust-bindings/sys/LICENSE b/rust-bindings/sys/LICENSE new file mode 100644 index 0000000000..bd32f32155 --- /dev/null +++ b/rust-bindings/sys/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2018, 2019, 2020 Felix Krull + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/rust-bindings/sys/build.rs b/rust-bindings/sys/build.rs new file mode 100644 index 0000000000..8c0c4a3a4a --- /dev/null +++ b/rust-bindings/sys/build.rs @@ -0,0 +1,17 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +#[cfg(not(feature = "dox"))] +use std::process; + +#[cfg(feature = "dox")] +fn main() {} // prevent linking libraries to avoid documentation failure + +#[cfg(not(feature = "dox"))] +fn main() { + if let Err(s) = system_deps::Config::new().probe() { + println!("cargo:warning={}", s); + process::exit(1); + } +} diff --git a/rust-bindings/sys/src/auto/versions.txt b/rust-bindings/sys/src/auto/versions.txt new file mode 100644 index 0000000000..5a1560025c --- /dev/null +++ b/rust-bindings/sys/src/auto/versions.txt @@ -0,0 +1,2 @@ +Generated by gir (https://github.com/gtk-rs/gir @ e8f82cf6) +from gir-files diff --git a/rust-bindings/sys/src/lib.rs b/rust-bindings/sys/src/lib.rs new file mode 100644 index 0000000000..2da5431b04 --- /dev/null +++ b/rust-bindings/sys/src/lib.rs @@ -0,0 +1,3788 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +#![allow(non_camel_case_types, non_upper_case_globals, non_snake_case)] +#![allow( + clippy::approx_constant, + clippy::type_complexity, + clippy::unreadable_literal, + clippy::upper_case_acronyms +)] +#![cfg_attr(feature = "dox", feature(doc_cfg))] + +use gio_sys as gio; +use glib_sys as glib; +use gobject_sys as gobject; + +mod manual; + +pub use manual::*; + +#[allow(unused_imports)] +use libc::{ + c_char, c_double, c_float, c_int, c_long, c_short, c_uchar, c_uint, c_ulong, c_ushort, c_void, + intptr_t, size_t, ssize_t, time_t, uintptr_t, FILE, +}; + +#[allow(unused_imports)] +use glib::{gboolean, gconstpointer, gpointer, GType}; + +// Aliases +pub type OstreeCollectionRefv = *mut *mut OstreeCollectionRef; +pub type OstreeRepoFinderResultv = *mut *mut OstreeRepoFinderResult; + +// Enums +pub type OstreeDeploymentUnlockedState = c_int; +pub const OSTREE_DEPLOYMENT_UNLOCKED_NONE: OstreeDeploymentUnlockedState = 0; +pub const OSTREE_DEPLOYMENT_UNLOCKED_DEVELOPMENT: OstreeDeploymentUnlockedState = 1; +pub const OSTREE_DEPLOYMENT_UNLOCKED_HOTFIX: OstreeDeploymentUnlockedState = 2; +pub const OSTREE_DEPLOYMENT_UNLOCKED_TRANSIENT: OstreeDeploymentUnlockedState = 3; + +pub type OstreeGpgError = c_int; +pub const OSTREE_GPG_ERROR_NO_SIGNATURE: OstreeGpgError = 0; +pub const OSTREE_GPG_ERROR_INVALID_SIGNATURE: OstreeGpgError = 1; +pub const OSTREE_GPG_ERROR_MISSING_KEY: OstreeGpgError = 2; +pub const OSTREE_GPG_ERROR_EXPIRED_SIGNATURE: OstreeGpgError = 3; +pub const OSTREE_GPG_ERROR_EXPIRED_KEY: OstreeGpgError = 4; +pub const OSTREE_GPG_ERROR_REVOKED_KEY: OstreeGpgError = 5; + +pub type OstreeGpgSignatureAttr = c_int; +pub const OSTREE_GPG_SIGNATURE_ATTR_VALID: OstreeGpgSignatureAttr = 0; +pub const OSTREE_GPG_SIGNATURE_ATTR_SIG_EXPIRED: OstreeGpgSignatureAttr = 1; +pub const OSTREE_GPG_SIGNATURE_ATTR_KEY_EXPIRED: OstreeGpgSignatureAttr = 2; +pub const OSTREE_GPG_SIGNATURE_ATTR_KEY_REVOKED: OstreeGpgSignatureAttr = 3; +pub const OSTREE_GPG_SIGNATURE_ATTR_KEY_MISSING: OstreeGpgSignatureAttr = 4; +pub const OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT: OstreeGpgSignatureAttr = 5; +pub const OSTREE_GPG_SIGNATURE_ATTR_TIMESTAMP: OstreeGpgSignatureAttr = 6; +pub const OSTREE_GPG_SIGNATURE_ATTR_EXP_TIMESTAMP: OstreeGpgSignatureAttr = 7; +pub const OSTREE_GPG_SIGNATURE_ATTR_PUBKEY_ALGO_NAME: OstreeGpgSignatureAttr = 8; +pub const OSTREE_GPG_SIGNATURE_ATTR_HASH_ALGO_NAME: OstreeGpgSignatureAttr = 9; +pub const OSTREE_GPG_SIGNATURE_ATTR_USER_NAME: OstreeGpgSignatureAttr = 10; +pub const OSTREE_GPG_SIGNATURE_ATTR_USER_EMAIL: OstreeGpgSignatureAttr = 11; +pub const OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT_PRIMARY: OstreeGpgSignatureAttr = 12; +pub const OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP: OstreeGpgSignatureAttr = 13; +pub const OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP_PRIMARY: OstreeGpgSignatureAttr = 14; + +pub type OstreeObjectType = c_int; +pub const OSTREE_OBJECT_TYPE_FILE: OstreeObjectType = 1; +pub const OSTREE_OBJECT_TYPE_DIR_TREE: OstreeObjectType = 2; +pub const OSTREE_OBJECT_TYPE_DIR_META: OstreeObjectType = 3; +pub const OSTREE_OBJECT_TYPE_COMMIT: OstreeObjectType = 4; +pub const OSTREE_OBJECT_TYPE_TOMBSTONE_COMMIT: OstreeObjectType = 5; +pub const OSTREE_OBJECT_TYPE_COMMIT_META: OstreeObjectType = 6; +pub const OSTREE_OBJECT_TYPE_PAYLOAD_LINK: OstreeObjectType = 7; +pub const OSTREE_OBJECT_TYPE_FILE_XATTRS: OstreeObjectType = 8; +pub const OSTREE_OBJECT_TYPE_FILE_XATTRS_LINK: OstreeObjectType = 9; + +pub type OstreeRepoCheckoutFilterResult = c_int; +pub const OSTREE_REPO_CHECKOUT_FILTER_ALLOW: OstreeRepoCheckoutFilterResult = 0; +pub const OSTREE_REPO_CHECKOUT_FILTER_SKIP: OstreeRepoCheckoutFilterResult = 1; + +pub type OstreeRepoCheckoutMode = c_int; +pub const OSTREE_REPO_CHECKOUT_MODE_NONE: OstreeRepoCheckoutMode = 0; +pub const OSTREE_REPO_CHECKOUT_MODE_USER: OstreeRepoCheckoutMode = 1; + +pub type OstreeRepoCheckoutOverwriteMode = c_int; +pub const OSTREE_REPO_CHECKOUT_OVERWRITE_NONE: OstreeRepoCheckoutOverwriteMode = 0; +pub const OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_FILES: OstreeRepoCheckoutOverwriteMode = 1; +pub const OSTREE_REPO_CHECKOUT_OVERWRITE_ADD_FILES: OstreeRepoCheckoutOverwriteMode = 2; +pub const OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_IDENTICAL: OstreeRepoCheckoutOverwriteMode = 3; + +pub type OstreeRepoCommitFilterResult = c_int; +pub const OSTREE_REPO_COMMIT_FILTER_ALLOW: OstreeRepoCommitFilterResult = 0; +pub const OSTREE_REPO_COMMIT_FILTER_SKIP: OstreeRepoCommitFilterResult = 1; + +pub type OstreeRepoCommitIterResult = c_int; +pub const OSTREE_REPO_COMMIT_ITER_RESULT_ERROR: OstreeRepoCommitIterResult = 0; +pub const OSTREE_REPO_COMMIT_ITER_RESULT_END: OstreeRepoCommitIterResult = 1; +pub const OSTREE_REPO_COMMIT_ITER_RESULT_FILE: OstreeRepoCommitIterResult = 2; +pub const OSTREE_REPO_COMMIT_ITER_RESULT_DIR: OstreeRepoCommitIterResult = 3; + +pub type OstreeRepoLockType = c_int; +pub const OSTREE_REPO_LOCK_SHARED: OstreeRepoLockType = 0; +pub const OSTREE_REPO_LOCK_EXCLUSIVE: OstreeRepoLockType = 1; + +pub type OstreeRepoMode = c_int; +pub const OSTREE_REPO_MODE_BARE: OstreeRepoMode = 0; +pub const OSTREE_REPO_MODE_ARCHIVE: OstreeRepoMode = 1; +pub const OSTREE_REPO_MODE_ARCHIVE_Z2: OstreeRepoMode = 1; +pub const OSTREE_REPO_MODE_BARE_USER: OstreeRepoMode = 2; +pub const OSTREE_REPO_MODE_BARE_USER_ONLY: OstreeRepoMode = 3; +pub const OSTREE_REPO_MODE_BARE_SPLIT_XATTRS: OstreeRepoMode = 4; + +pub type OstreeRepoRemoteChange = c_int; +pub const OSTREE_REPO_REMOTE_CHANGE_ADD: OstreeRepoRemoteChange = 0; +pub const OSTREE_REPO_REMOTE_CHANGE_ADD_IF_NOT_EXISTS: OstreeRepoRemoteChange = 1; +pub const OSTREE_REPO_REMOTE_CHANGE_DELETE: OstreeRepoRemoteChange = 2; +pub const OSTREE_REPO_REMOTE_CHANGE_DELETE_IF_EXISTS: OstreeRepoRemoteChange = 3; +pub const OSTREE_REPO_REMOTE_CHANGE_REPLACE: OstreeRepoRemoteChange = 4; + +pub type OstreeStaticDeltaGenerateOpt = c_int; +pub const OSTREE_STATIC_DELTA_GENERATE_OPT_LOWLATENCY: OstreeStaticDeltaGenerateOpt = 0; +pub const OSTREE_STATIC_DELTA_GENERATE_OPT_MAJOR: OstreeStaticDeltaGenerateOpt = 1; + +pub type OstreeStaticDeltaIndexFlags = c_int; +pub const OSTREE_STATIC_DELTA_INDEX_FLAGS_NONE: OstreeStaticDeltaIndexFlags = 0; + +// Constants +pub const OSTREE_COMMIT_GVARIANT_STRING: *const c_char = + b"(a{sv}aya(say)sstayay)\0" as *const u8 as *const c_char; +pub const OSTREE_COMMIT_META_KEY_ARCHITECTURE: *const c_char = + b"ostree.architecture\0" as *const u8 as *const c_char; +pub const OSTREE_COMMIT_META_KEY_COLLECTION_BINDING: *const c_char = + b"ostree.collection-binding\0" as *const u8 as *const c_char; +pub const OSTREE_COMMIT_META_KEY_ENDOFLIFE: *const c_char = + b"ostree.endoflife\0" as *const u8 as *const c_char; +pub const OSTREE_COMMIT_META_KEY_ENDOFLIFE_REBASE: *const c_char = + b"ostree.endoflife-rebase\0" as *const u8 as *const c_char; +pub const OSTREE_COMMIT_META_KEY_REF_BINDING: *const c_char = + b"ostree.ref-binding\0" as *const u8 as *const c_char; +pub const OSTREE_COMMIT_META_KEY_SOURCE_TITLE: *const c_char = + b"ostree.source-title\0" as *const u8 as *const c_char; +pub const OSTREE_COMMIT_META_KEY_VERSION: *const c_char = + b"version\0" as *const u8 as *const c_char; +pub const OSTREE_DIRMETA_GVARIANT_STRING: *const c_char = + b"(uuua(ayay))\0" as *const u8 as *const c_char; +pub const OSTREE_FILEMETA_GVARIANT_STRING: *const c_char = + b"(uuua(ayay))\0" as *const u8 as *const c_char; +pub const OSTREE_GPG_KEY_GVARIANT_STRING: *const c_char = + b"(aa{sv}aa{sv}a{sv})\0" as *const u8 as *const c_char; +pub const OSTREE_MAX_METADATA_SIZE: c_int = 10485760; +pub const OSTREE_MAX_METADATA_WARN_SIZE: c_int = 7340032; +pub const OSTREE_METADATA_KEY_BOOTABLE: *const c_char = + b"ostree.bootable\0" as *const u8 as *const c_char; +pub const OSTREE_METADATA_KEY_LINUX: *const c_char = + b"ostree.linux\0" as *const u8 as *const c_char; +pub const OSTREE_META_KEY_DEPLOY_COLLECTION_ID: *const c_char = + b"ostree.deploy-collection-id\0" as *const u8 as *const c_char; +pub const OSTREE_ORIGIN_TRANSIENT_GROUP: *const c_char = + b"libostree-transient\0" as *const u8 as *const c_char; +pub const OSTREE_PATH_BOOTED: *const c_char = b"/run/ostree-booted\0" as *const u8 as *const c_char; +pub const OSTREE_REPO_METADATA_REF: *const c_char = + b"ostree-metadata\0" as *const u8 as *const c_char; +pub const OSTREE_SHA256_DIGEST_LEN: c_int = 32; +pub const OSTREE_SHA256_STRING_LEN: c_int = 64; +pub const OSTREE_SIGN_NAME_ED25519: *const c_char = b"ed25519\0" as *const u8 as *const c_char; +pub const OSTREE_SUMMARY_GVARIANT_STRING: *const c_char = + b"(a(s(taya{sv}))a{sv})\0" as *const u8 as *const c_char; +pub const OSTREE_SUMMARY_SIG_GVARIANT_STRING: *const c_char = + b"a{sv}\0" as *const u8 as *const c_char; +pub const OSTREE_TIMESTAMP: c_int = 0; +pub const OSTREE_TREE_GVARIANT_STRING: *const c_char = + b"(a(say)a(sayay))\0" as *const u8 as *const c_char; + +// Flags +pub type OstreeChecksumFlags = c_uint; +pub const OSTREE_CHECKSUM_FLAGS_NONE: OstreeChecksumFlags = 0; +pub const OSTREE_CHECKSUM_FLAGS_IGNORE_XATTRS: OstreeChecksumFlags = 1; +pub const OSTREE_CHECKSUM_FLAGS_CANONICAL_PERMISSIONS: OstreeChecksumFlags = 2; + +pub type OstreeDiffFlags = c_uint; +pub const OSTREE_DIFF_FLAGS_NONE: OstreeDiffFlags = 0; +pub const OSTREE_DIFF_FLAGS_IGNORE_XATTRS: OstreeDiffFlags = 1; + +pub type OstreeGpgSignatureFormatFlags = c_uint; +pub const OSTREE_GPG_SIGNATURE_FORMAT_DEFAULT: OstreeGpgSignatureFormatFlags = 0; + +pub type OstreeRepoCommitModifierFlags = c_uint; +pub const OSTREE_REPO_COMMIT_MODIFIER_FLAGS_NONE: OstreeRepoCommitModifierFlags = 0; +pub const OSTREE_REPO_COMMIT_MODIFIER_FLAGS_SKIP_XATTRS: OstreeRepoCommitModifierFlags = 1; +pub const OSTREE_REPO_COMMIT_MODIFIER_FLAGS_GENERATE_SIZES: OstreeRepoCommitModifierFlags = 2; +pub const OSTREE_REPO_COMMIT_MODIFIER_FLAGS_CANONICAL_PERMISSIONS: OstreeRepoCommitModifierFlags = + 4; +pub const OSTREE_REPO_COMMIT_MODIFIER_FLAGS_ERROR_ON_UNLABELED: OstreeRepoCommitModifierFlags = 8; +pub const OSTREE_REPO_COMMIT_MODIFIER_FLAGS_CONSUME: OstreeRepoCommitModifierFlags = 16; +pub const OSTREE_REPO_COMMIT_MODIFIER_FLAGS_DEVINO_CANONICAL: OstreeRepoCommitModifierFlags = 32; + +pub type OstreeRepoCommitState = c_uint; +pub const OSTREE_REPO_COMMIT_STATE_NORMAL: OstreeRepoCommitState = 0; +pub const OSTREE_REPO_COMMIT_STATE_PARTIAL: OstreeRepoCommitState = 1; +pub const OSTREE_REPO_COMMIT_STATE_FSCK_PARTIAL: OstreeRepoCommitState = 2; + +pub type OstreeRepoCommitTraverseFlags = c_uint; +pub const OSTREE_REPO_COMMIT_TRAVERSE_FLAG_NONE: OstreeRepoCommitTraverseFlags = 1; +pub const OSTREE_REPO_COMMIT_TRAVERSE_FLAG_COMMIT_ONLY: OstreeRepoCommitTraverseFlags = 2; + +pub type OstreeRepoListObjectsFlags = c_uint; +pub const OSTREE_REPO_LIST_OBJECTS_LOOSE: OstreeRepoListObjectsFlags = 1; +pub const OSTREE_REPO_LIST_OBJECTS_PACKED: OstreeRepoListObjectsFlags = 2; +pub const OSTREE_REPO_LIST_OBJECTS_ALL: OstreeRepoListObjectsFlags = 4; +pub const OSTREE_REPO_LIST_OBJECTS_NO_PARENTS: OstreeRepoListObjectsFlags = 8; + +pub type OstreeRepoListRefsExtFlags = c_uint; +pub const OSTREE_REPO_LIST_REFS_EXT_NONE: OstreeRepoListRefsExtFlags = 0; +pub const OSTREE_REPO_LIST_REFS_EXT_ALIASES: OstreeRepoListRefsExtFlags = 1; +pub const OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_REMOTES: OstreeRepoListRefsExtFlags = 2; +pub const OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_MIRRORS: OstreeRepoListRefsExtFlags = 4; + +pub type OstreeRepoPruneFlags = c_uint; +pub const OSTREE_REPO_PRUNE_FLAGS_NONE: OstreeRepoPruneFlags = 0; +pub const OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE: OstreeRepoPruneFlags = 1; +pub const OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY: OstreeRepoPruneFlags = 2; +pub const OSTREE_REPO_PRUNE_FLAGS_COMMIT_ONLY: OstreeRepoPruneFlags = 4; + +pub type OstreeRepoPullFlags = c_uint; +pub const OSTREE_REPO_PULL_FLAGS_NONE: OstreeRepoPullFlags = 0; +pub const OSTREE_REPO_PULL_FLAGS_MIRROR: OstreeRepoPullFlags = 1; +pub const OSTREE_REPO_PULL_FLAGS_COMMIT_ONLY: OstreeRepoPullFlags = 2; +pub const OSTREE_REPO_PULL_FLAGS_UNTRUSTED: OstreeRepoPullFlags = 4; +pub const OSTREE_REPO_PULL_FLAGS_BAREUSERONLY_FILES: OstreeRepoPullFlags = 8; +pub const OSTREE_REPO_PULL_FLAGS_TRUSTED_HTTP: OstreeRepoPullFlags = 16; + +pub type OstreeRepoResolveRevExtFlags = c_uint; +pub const OSTREE_REPO_RESOLVE_REV_EXT_NONE: OstreeRepoResolveRevExtFlags = 0; +pub const OSTREE_REPO_RESOLVE_REV_EXT_LOCAL_ONLY: OstreeRepoResolveRevExtFlags = 1; + +pub type OstreeRepoVerifyFlags = c_uint; +pub const OSTREE_REPO_VERIFY_FLAGS_NONE: OstreeRepoVerifyFlags = 0; +pub const OSTREE_REPO_VERIFY_FLAGS_NO_GPG: OstreeRepoVerifyFlags = 1; +pub const OSTREE_REPO_VERIFY_FLAGS_NO_SIGNAPI: OstreeRepoVerifyFlags = 2; + +pub type OstreeSePolicyRestoreconFlags = c_uint; +pub const OSTREE_SEPOLICY_RESTORECON_FLAGS_NONE: OstreeSePolicyRestoreconFlags = 0; +pub const OSTREE_SEPOLICY_RESTORECON_FLAGS_ALLOW_NOLABEL: OstreeSePolicyRestoreconFlags = 1; +pub const OSTREE_SEPOLICY_RESTORECON_FLAGS_KEEP_EXISTING: OstreeSePolicyRestoreconFlags = 2; + +pub type OstreeSysrootSimpleWriteDeploymentFlags = c_uint; +pub const OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NONE: + OstreeSysrootSimpleWriteDeploymentFlags = 0; +pub const OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN: + OstreeSysrootSimpleWriteDeploymentFlags = 1; +pub const OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NOT_DEFAULT: + OstreeSysrootSimpleWriteDeploymentFlags = 2; +pub const OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NO_CLEAN: + OstreeSysrootSimpleWriteDeploymentFlags = 4; +pub const OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_PENDING: + OstreeSysrootSimpleWriteDeploymentFlags = 8; +pub const OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_ROLLBACK: + OstreeSysrootSimpleWriteDeploymentFlags = 16; + +pub type OstreeSysrootUpgraderFlags = c_uint; +pub const OSTREE_SYSROOT_UPGRADER_FLAGS_IGNORE_UNCONFIGURED: OstreeSysrootUpgraderFlags = 2; +pub const OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE: OstreeSysrootUpgraderFlags = 4; + +pub type OstreeSysrootUpgraderPullFlags = c_uint; +pub const OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_NONE: OstreeSysrootUpgraderPullFlags = 0; +pub const OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_ALLOW_OLDER: OstreeSysrootUpgraderPullFlags = 1; +pub const OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_SYNTHETIC: OstreeSysrootUpgraderPullFlags = 2; + +// Callbacks +pub type OstreeRepoCheckoutFilter = Option< + unsafe extern "C" fn( + *mut OstreeRepo, + *const c_char, + *mut stat, + gpointer, + ) -> OstreeRepoCheckoutFilterResult, +>; +pub type OstreeRepoCommitFilter = Option< + unsafe extern "C" fn( + *mut OstreeRepo, + *const c_char, + *mut gio::GFileInfo, + gpointer, + ) -> OstreeRepoCommitFilterResult, +>; +pub type OstreeRepoCommitModifierXattrCallback = Option< + unsafe extern "C" fn( + *mut OstreeRepo, + *const c_char, + *mut gio::GFileInfo, + gpointer, + ) -> *mut glib::GVariant, +>; +pub type OstreeRepoImportArchiveTranslatePathname = Option< + unsafe extern "C" fn(*mut OstreeRepo, *const stat, *const c_char, gpointer) -> *mut c_char, +>; + +// Records +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeAsyncProgressClass { + pub parent_class: gobject::GObjectClass, + pub changed: Option<unsafe extern "C" fn(*mut OstreeAsyncProgress, gpointer)>, +} + +impl ::std::fmt::Debug for OstreeAsyncProgressClass { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeAsyncProgressClass @ {:p}", self)) + .field("parent_class", &self.parent_class) + .field("changed", &self.changed) + .finish() + } +} + +#[repr(C)] +pub struct _OstreeBootloader(c_void); + +pub type OstreeBootloader = *mut _OstreeBootloader; + +#[repr(C)] +pub struct _OstreeBootloaderGrub2(c_void); + +pub type OstreeBootloaderGrub2 = *mut _OstreeBootloaderGrub2; + +#[repr(C)] +pub struct _OstreeBootloaderSyslinux(c_void); + +pub type OstreeBootloaderSyslinux = *mut _OstreeBootloaderSyslinux; + +#[repr(C)] +pub struct _OstreeBootloaderUboot(c_void); + +pub type OstreeBootloaderUboot = *mut _OstreeBootloaderUboot; + +#[repr(C)] +pub struct _OstreeBootloaderZipl(c_void); + +pub type OstreeBootloaderZipl = *mut _OstreeBootloaderZipl; + +#[repr(C)] +pub struct _OstreeChecksumInputStreamPrivate(c_void); + +pub type OstreeChecksumInputStreamPrivate = *mut _OstreeChecksumInputStreamPrivate; + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeCollectionRef { + pub collection_id: *mut c_char, + pub ref_name: *mut c_char, +} + +impl ::std::fmt::Debug for OstreeCollectionRef { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeCollectionRef @ {:p}", self)) + .field("collection_id", &self.collection_id) + .field("ref_name", &self.ref_name) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeCommitSizesEntry { + pub checksum: *mut c_char, + pub objtype: OstreeObjectType, + pub unpacked: u64, + pub archived: u64, +} + +impl ::std::fmt::Debug for OstreeCommitSizesEntry { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeCommitSizesEntry @ {:p}", self)) + .field("checksum", &self.checksum) + .field("objtype", &self.objtype) + .field("unpacked", &self.unpacked) + .field("archived", &self.archived) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeContentWriterClass { + pub parent_class: gio::GOutputStreamClass, +} + +impl ::std::fmt::Debug for OstreeContentWriterClass { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeContentWriterClass @ {:p}", self)) + .field("parent_class", &self.parent_class) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeDiffDirsOptions { + pub owner_uid: c_int, + pub owner_gid: c_int, + pub devino_to_csum_cache: *mut OstreeRepoDevInoCache, + pub unused_bools: [gboolean; 7], + pub unused_ints: [c_int; 6], + pub unused_ptrs: [gpointer; 7], +} + +impl ::std::fmt::Debug for OstreeDiffDirsOptions { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeDiffDirsOptions @ {:p}", self)) + .field("owner_uid", &self.owner_uid) + .field("owner_gid", &self.owner_gid) + .field("devino_to_csum_cache", &self.devino_to_csum_cache) + .field("unused_bools", &self.unused_bools) + .field("unused_ints", &self.unused_ints) + .field("unused_ptrs", &self.unused_ptrs) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeDiffItem { + pub refcount: c_int, + pub src: *mut gio::GFile, + pub target: *mut gio::GFile, + pub src_info: *mut gio::GFileInfo, + pub target_info: *mut gio::GFileInfo, + pub src_checksum: *mut c_char, + pub target_checksum: *mut c_char, +} + +impl ::std::fmt::Debug for OstreeDiffItem { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeDiffItem @ {:p}", self)) + .field("refcount", &self.refcount) + .field("src", &self.src) + .field("target", &self.target) + .field("src_info", &self.src_info) + .field("target_info", &self.target_info) + .field("src_checksum", &self.src_checksum) + .field("target_checksum", &self.target_checksum) + .finish() + } +} + +#[repr(C)] +pub struct _OstreeGpgVerifier(c_void); + +pub type OstreeGpgVerifier = *mut _OstreeGpgVerifier; + +#[repr(C)] +pub struct _OstreeKernelArgs(c_void); + +pub type OstreeKernelArgs = *mut _OstreeKernelArgs; + +#[repr(C)] +pub struct _OstreeKernelArgsEntry(c_void); + +pub type OstreeKernelArgsEntry = *mut _OstreeKernelArgsEntry; + +#[repr(C)] +pub struct _OstreeLibarchiveInputStreamPrivate(c_void); + +pub type OstreeLibarchiveInputStreamPrivate = *mut _OstreeLibarchiveInputStreamPrivate; + +#[repr(C)] +pub struct _OstreeLzmaCompressor(c_void); + +pub type OstreeLzmaCompressor = *mut _OstreeLzmaCompressor; + +#[repr(C)] +pub struct _OstreeLzmaDecompressor(c_void); + +pub type OstreeLzmaDecompressor = *mut _OstreeLzmaDecompressor; + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeMutableTreeClass { + pub parent_class: gobject::GObjectClass, +} + +impl ::std::fmt::Debug for OstreeMutableTreeClass { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeMutableTreeClass @ {:p}", self)) + .field("parent_class", &self.parent_class) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeMutableTreeIter { + pub in_files: gboolean, + pub iter: glib::GHashTableIter, +} + +impl ::std::fmt::Debug for OstreeMutableTreeIter { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeMutableTreeIter @ {:p}", self)) + .field("in_files", &self.in_files) + .field("iter", &self.iter) + .finish() + } +} + +#[repr(C)] +pub struct OstreeRemote(c_void); + +impl ::std::fmt::Debug for OstreeRemote { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRemote @ {:p}", self)) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeRepoCheckoutAtOptions { + pub mode: OstreeRepoCheckoutMode, + pub overwrite_mode: OstreeRepoCheckoutOverwriteMode, + pub enable_uncompressed_cache: gboolean, + pub enable_fsync: gboolean, + pub process_whiteouts: gboolean, + pub no_copy_fallback: gboolean, + pub force_copy: gboolean, + pub bareuseronly_dirs: gboolean, + pub force_copy_zerosized: gboolean, + pub unused_bools: [gboolean; 4], + pub subpath: *const c_char, + pub devino_to_csum_cache: *mut OstreeRepoDevInoCache, + pub unused_ints: [c_int; 6], + pub unused_ptrs: [gpointer; 3], + pub filter: OstreeRepoCheckoutFilter, + pub filter_user_data: gpointer, + pub sepolicy: *mut OstreeSePolicy, + pub sepolicy_prefix: *const c_char, +} + +impl ::std::fmt::Debug for OstreeRepoCheckoutAtOptions { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoCheckoutAtOptions @ {:p}", self)) + .field("mode", &self.mode) + .field("overwrite_mode", &self.overwrite_mode) + .field("enable_uncompressed_cache", &self.enable_uncompressed_cache) + .field("enable_fsync", &self.enable_fsync) + .field("process_whiteouts", &self.process_whiteouts) + .field("no_copy_fallback", &self.no_copy_fallback) + .field("force_copy", &self.force_copy) + .field("bareuseronly_dirs", &self.bareuseronly_dirs) + .field("force_copy_zerosized", &self.force_copy_zerosized) + .field("unused_bools", &self.unused_bools) + .field("subpath", &self.subpath) + .field("devino_to_csum_cache", &self.devino_to_csum_cache) + .field("unused_ints", &self.unused_ints) + .field("unused_ptrs", &self.unused_ptrs) + .field("filter", &self.filter) + .field("filter_user_data", &self.filter_user_data) + .field("sepolicy", &self.sepolicy) + .field("sepolicy_prefix", &self.sepolicy_prefix) + .finish() + } +} + +#[repr(C)] +pub struct OstreeRepoCheckoutOptions { + pub mode: OstreeRepoCheckoutMode, + pub overwrite_mode: OstreeRepoCheckoutOverwriteMode, + pub enable_uncompressed_cache: c_uint, + _truncated_record_marker: c_void, + // field disable_fsync has incomplete type +} + +impl ::std::fmt::Debug for OstreeRepoCheckoutOptions { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoCheckoutOptions @ {:p}", self)) + .field("mode", &self.mode) + .field("overwrite_mode", &self.overwrite_mode) + .field("enable_uncompressed_cache", &self.enable_uncompressed_cache) + .finish() + } +} + +#[repr(C)] +pub struct OstreeRepoCommitModifier(c_void); + +impl ::std::fmt::Debug for OstreeRepoCommitModifier { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoCommitModifier @ {:p}", self)) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeRepoCommitTraverseIter { + pub initialized: gboolean, + pub dummy: [gpointer; 10], + pub dummy_checksum_data: [c_char; 130], +} + +impl ::std::fmt::Debug for OstreeRepoCommitTraverseIter { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoCommitTraverseIter @ {:p}", self)) + .field("initialized", &self.initialized) + .field("dummy", &self.dummy) + .finish() + } +} + +#[repr(C)] +pub struct OstreeRepoDevInoCache(c_void); + +impl ::std::fmt::Debug for OstreeRepoDevInoCache { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoDevInoCache @ {:p}", self)) + .finish() + } +} + +#[repr(C)] +pub struct OstreeRepoExportArchiveOptions { + pub disable_xattrs: c_uint, + _truncated_record_marker: c_void, + // field reserved has incomplete type +} + +impl ::std::fmt::Debug for OstreeRepoExportArchiveOptions { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoExportArchiveOptions @ {:p}", self)) + .field("disable_xattrs", &self.disable_xattrs) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeRepoFileClass { + pub parent_class: gobject::GObjectClass, +} + +impl ::std::fmt::Debug for OstreeRepoFileClass { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoFileClass @ {:p}", self)) + .field("parent_class", &self.parent_class) + .finish() + } +} + +#[repr(C)] +pub struct _OstreeRepoFileEnumerator(c_void); + +pub type OstreeRepoFileEnumerator = *mut _OstreeRepoFileEnumerator; + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeRepoFinderAvahiClass { + pub parent_class: gobject::GObjectClass, +} + +impl ::std::fmt::Debug for OstreeRepoFinderAvahiClass { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoFinderAvahiClass @ {:p}", self)) + .field("parent_class", &self.parent_class) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeRepoFinderConfigClass { + pub parent_class: gobject::GObjectClass, +} + +impl ::std::fmt::Debug for OstreeRepoFinderConfigClass { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoFinderConfigClass @ {:p}", self)) + .field("parent_class", &self.parent_class) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeRepoFinderInterface { + pub g_iface: gobject::GTypeInterface, + pub resolve_async: Option< + unsafe extern "C" fn( + *mut OstreeRepoFinder, + *const *const OstreeCollectionRef, + *mut OstreeRepo, + *mut gio::GCancellable, + gio::GAsyncReadyCallback, + gpointer, + ), + >, + pub resolve_finish: Option< + unsafe extern "C" fn( + *mut OstreeRepoFinder, + *mut gio::GAsyncResult, + *mut *mut glib::GError, + ) -> *mut glib::GPtrArray, + >, +} + +impl ::std::fmt::Debug for OstreeRepoFinderInterface { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoFinderInterface @ {:p}", self)) + .field("g_iface", &self.g_iface) + .field("resolve_async", &self.resolve_async) + .field("resolve_finish", &self.resolve_finish) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeRepoFinderMountClass { + pub parent_class: gobject::GObjectClass, +} + +impl ::std::fmt::Debug for OstreeRepoFinderMountClass { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoFinderMountClass @ {:p}", self)) + .field("parent_class", &self.parent_class) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeRepoFinderOverrideClass { + pub parent_class: gobject::GObjectClass, +} + +impl ::std::fmt::Debug for OstreeRepoFinderOverrideClass { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoFinderOverrideClass @ {:p}", self)) + .field("parent_class", &self.parent_class) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeRepoFinderResult { + pub remote: *mut OstreeRemote, + pub finder: *mut OstreeRepoFinder, + pub priority: c_int, + pub ref_to_checksum: *mut glib::GHashTable, + pub summary_last_modified: u64, + pub ref_to_timestamp: *mut glib::GHashTable, + pub padding: [gpointer; 3], +} + +impl ::std::fmt::Debug for OstreeRepoFinderResult { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoFinderResult @ {:p}", self)) + .field("remote", &self.remote) + .field("finder", &self.finder) + .field("priority", &self.priority) + .field("ref_to_checksum", &self.ref_to_checksum) + .field("summary_last_modified", &self.summary_last_modified) + .field("ref_to_timestamp", &self.ref_to_timestamp) + .finish() + } +} + +#[repr(C)] +pub struct OstreeRepoImportArchiveOptions { + pub ignore_unsupported_content: c_uint, + _truncated_record_marker: c_void, + // field autocreate_parents has incomplete type +} + +impl ::std::fmt::Debug for OstreeRepoImportArchiveOptions { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoImportArchiveOptions @ {:p}", self)) + .field( + "ignore_unsupported_content", + &self.ignore_unsupported_content, + ) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeRepoPruneOptions { + pub flags: OstreeRepoPruneFlags, + pub reachable: *mut glib::GHashTable, + pub unused_bools: [gboolean; 6], + pub unused_ints: [c_int; 6], + pub unused_ptrs: [gpointer; 7], +} + +impl ::std::fmt::Debug for OstreeRepoPruneOptions { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoPruneOptions @ {:p}", self)) + .field("flags", &self.flags) + .field("reachable", &self.reachable) + .field("unused_bools", &self.unused_bools) + .field("unused_ints", &self.unused_ints) + .field("unused_ptrs", &self.unused_ptrs) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeRepoTransactionStats { + pub metadata_objects_total: c_uint, + pub metadata_objects_written: c_uint, + pub content_objects_total: c_uint, + pub content_objects_written: c_uint, + pub content_bytes_written: u64, + pub devino_cache_hits: c_uint, + pub padding1: c_uint, + pub padding2: u64, + pub padding3: u64, + pub padding4: u64, +} + +impl ::std::fmt::Debug for OstreeRepoTransactionStats { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoTransactionStats @ {:p}", self)) + .field("metadata_objects_total", &self.metadata_objects_total) + .field("metadata_objects_written", &self.metadata_objects_written) + .field("content_objects_total", &self.content_objects_total) + .field("content_objects_written", &self.content_objects_written) + .field("content_bytes_written", &self.content_bytes_written) + .field("devino_cache_hits", &self.devino_cache_hits) + .field("padding1", &self.padding1) + .field("padding2", &self.padding2) + .field("padding3", &self.padding3) + .field("padding4", &self.padding4) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeSignInterface { + pub g_iface: gobject::GTypeInterface, + pub get_name: Option<unsafe extern "C" fn(*mut OstreeSign) -> *const c_char>, + pub data: Option< + unsafe extern "C" fn( + *mut OstreeSign, + *mut glib::GBytes, + *mut *mut glib::GBytes, + *mut gio::GCancellable, + *mut *mut glib::GError, + ) -> gboolean, + >, + pub data_verify: Option< + unsafe extern "C" fn( + *mut OstreeSign, + *mut glib::GBytes, + *mut glib::GVariant, + *mut *mut c_char, + *mut *mut glib::GError, + ) -> gboolean, + >, + pub metadata_key: Option<unsafe extern "C" fn(*mut OstreeSign) -> *const c_char>, + pub metadata_format: Option<unsafe extern "C" fn(*mut OstreeSign) -> *const c_char>, + pub clear_keys: + Option<unsafe extern "C" fn(*mut OstreeSign, *mut *mut glib::GError) -> gboolean>, + pub set_sk: Option< + unsafe extern "C" fn( + *mut OstreeSign, + *mut glib::GVariant, + *mut *mut glib::GError, + ) -> gboolean, + >, + pub set_pk: Option< + unsafe extern "C" fn( + *mut OstreeSign, + *mut glib::GVariant, + *mut *mut glib::GError, + ) -> gboolean, + >, + pub add_pk: Option< + unsafe extern "C" fn( + *mut OstreeSign, + *mut glib::GVariant, + *mut *mut glib::GError, + ) -> gboolean, + >, + pub load_pk: Option< + unsafe extern "C" fn( + *mut OstreeSign, + *mut glib::GVariant, + *mut *mut glib::GError, + ) -> gboolean, + >, +} + +impl ::std::fmt::Debug for OstreeSignInterface { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeSignInterface @ {:p}", self)) + .field("g_iface", &self.g_iface) + .field("get_name", &self.get_name) + .field("data", &self.data) + .field("data_verify", &self.data_verify) + .field("metadata_key", &self.metadata_key) + .field("metadata_format", &self.metadata_format) + .field("clear_keys", &self.clear_keys) + .field("set_sk", &self.set_sk) + .field("set_pk", &self.set_pk) + .field("add_pk", &self.add_pk) + .field("load_pk", &self.load_pk) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeSysrootDeployTreeOpts { + pub unused_bools: [gboolean; 8], + pub unused_ints: [c_int; 8], + pub override_kernel_argv: *mut *mut c_char, + pub overlay_initrds: *mut *mut c_char, + pub unused_ptrs: [gpointer; 6], +} + +impl ::std::fmt::Debug for OstreeSysrootDeployTreeOpts { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeSysrootDeployTreeOpts @ {:p}", self)) + .field("unused_bools", &self.unused_bools) + .field("unused_ints", &self.unused_ints) + .field("override_kernel_argv", &self.override_kernel_argv) + .field("overlay_initrds", &self.overlay_initrds) + .field("unused_ptrs", &self.unused_ptrs) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct OstreeSysrootWriteDeploymentsOpts { + pub do_postclean: gboolean, + pub unused_bools: [gboolean; 7], + pub unused_ints: [c_int; 7], + pub unused_ptrs: [gpointer; 7], +} + +impl ::std::fmt::Debug for OstreeSysrootWriteDeploymentsOpts { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeSysrootWriteDeploymentsOpts @ {:p}", self)) + .field("do_postclean", &self.do_postclean) + .field("unused_bools", &self.unused_bools) + .field("unused_ints", &self.unused_ints) + .field("unused_ptrs", &self.unused_ptrs) + .finish() + } +} + +// Classes +#[repr(C)] +pub struct OstreeAsyncProgress(c_void); + +impl ::std::fmt::Debug for OstreeAsyncProgress { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeAsyncProgress @ {:p}", self)) + .finish() + } +} + +#[repr(C)] +pub struct OstreeBootconfigParser(c_void); + +impl ::std::fmt::Debug for OstreeBootconfigParser { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeBootconfigParser @ {:p}", self)) + .finish() + } +} + +#[repr(C)] +pub struct OstreeContentWriter(c_void); + +impl ::std::fmt::Debug for OstreeContentWriter { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeContentWriter @ {:p}", self)) + .finish() + } +} + +#[repr(C)] +pub struct OstreeDeployment(c_void); + +impl ::std::fmt::Debug for OstreeDeployment { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeDeployment @ {:p}", self)) + .finish() + } +} + +#[repr(C)] +pub struct OstreeGpgVerifyResult(c_void); + +impl ::std::fmt::Debug for OstreeGpgVerifyResult { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeGpgVerifyResult @ {:p}", self)) + .finish() + } +} + +#[repr(C)] +pub struct OstreeMutableTree(c_void); + +impl ::std::fmt::Debug for OstreeMutableTree { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeMutableTree @ {:p}", self)) + .finish() + } +} + +#[repr(C)] +pub struct OstreeRepo(c_void); + +impl ::std::fmt::Debug for OstreeRepo { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepo @ {:p}", self)).finish() + } +} + +#[repr(C)] +pub struct OstreeRepoFile(c_void); + +impl ::std::fmt::Debug for OstreeRepoFile { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoFile @ {:p}", self)) + .finish() + } +} + +#[repr(C)] +pub struct OstreeRepoFinderAvahi(c_void); + +impl ::std::fmt::Debug for OstreeRepoFinderAvahi { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoFinderAvahi @ {:p}", self)) + .finish() + } +} + +#[repr(C)] +pub struct OstreeRepoFinderConfig(c_void); + +impl ::std::fmt::Debug for OstreeRepoFinderConfig { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoFinderConfig @ {:p}", self)) + .finish() + } +} + +#[repr(C)] +pub struct OstreeRepoFinderMount(c_void); + +impl ::std::fmt::Debug for OstreeRepoFinderMount { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoFinderMount @ {:p}", self)) + .finish() + } +} + +#[repr(C)] +pub struct OstreeRepoFinderOverride(c_void); + +impl ::std::fmt::Debug for OstreeRepoFinderOverride { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeRepoFinderOverride @ {:p}", self)) + .finish() + } +} + +#[repr(C)] +pub struct OstreeSePolicy(c_void); + +impl ::std::fmt::Debug for OstreeSePolicy { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeSePolicy @ {:p}", self)) + .finish() + } +} + +#[repr(C)] +pub struct OstreeSysroot(c_void); + +impl ::std::fmt::Debug for OstreeSysroot { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeSysroot @ {:p}", self)) + .finish() + } +} + +#[repr(C)] +pub struct OstreeSysrootUpgrader(c_void); + +impl ::std::fmt::Debug for OstreeSysrootUpgrader { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("OstreeSysrootUpgrader @ {:p}", self)) + .finish() + } +} + +// Interfaces +#[repr(C)] +pub struct OstreeRepoFinder(c_void); + +impl ::std::fmt::Debug for OstreeRepoFinder { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + write!(f, "OstreeRepoFinder @ {:p}", self) + } +} + +#[repr(C)] +pub struct OstreeSign(c_void); + +impl ::std::fmt::Debug for OstreeSign { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + write!(f, "OstreeSign @ {:p}", self) + } +} + +#[link(name = "ostree-1")] +extern "C" { + + //========================================================================= + // OstreeSysrootUpgraderFlags + //========================================================================= + pub fn ostree_sysroot_upgrader_flags_get_type() -> GType; + + //========================================================================= + // OstreeCollectionRef + //========================================================================= + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_collection_ref_get_type() -> GType; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_collection_ref_new( + collection_id: *const c_char, + ref_name: *const c_char, + ) -> *mut OstreeCollectionRef; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_collection_ref_dup(ref_: *const OstreeCollectionRef) -> *mut OstreeCollectionRef; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_collection_ref_free(ref_: *mut OstreeCollectionRef); + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_collection_ref_dupv( + refs: *const *const OstreeCollectionRef, + ) -> *mut *mut OstreeCollectionRef; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_collection_ref_equal(ref1: gconstpointer, ref2: gconstpointer) -> gboolean; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_collection_ref_freev(refs: *mut *mut OstreeCollectionRef); + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_collection_ref_hash(ref_: gconstpointer) -> c_uint; + + //========================================================================= + // OstreeCommitSizesEntry + //========================================================================= + #[cfg(any(feature = "v2020_1", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_1")))] + pub fn ostree_commit_sizes_entry_get_type() -> GType; + #[cfg(any(feature = "v2020_1", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_1")))] + pub fn ostree_commit_sizes_entry_new( + checksum: *const c_char, + objtype: OstreeObjectType, + unpacked: u64, + archived: u64, + ) -> *mut OstreeCommitSizesEntry; + #[cfg(any(feature = "v2020_1", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_1")))] + pub fn ostree_commit_sizes_entry_copy( + entry: *const OstreeCommitSizesEntry, + ) -> *mut OstreeCommitSizesEntry; + #[cfg(any(feature = "v2020_1", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_1")))] + pub fn ostree_commit_sizes_entry_free(entry: *mut OstreeCommitSizesEntry); + + //========================================================================= + // OstreeDiffItem + //========================================================================= + pub fn ostree_diff_item_get_type() -> GType; + pub fn ostree_diff_item_ref(diffitem: *mut OstreeDiffItem) -> *mut OstreeDiffItem; + pub fn ostree_diff_item_unref(diffitem: *mut OstreeDiffItem); + + //========================================================================= + // OstreeKernelArgs + //========================================================================= + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_append(kargs: *mut OstreeKernelArgs, arg: *const c_char); + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_append_argv(kargs: *mut OstreeKernelArgs, argv: *mut *mut c_char); + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_append_argv_filtered( + kargs: *mut OstreeKernelArgs, + argv: *mut *mut c_char, + prefixes: *mut *mut c_char, + ); + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_append_proc_cmdline( + kargs: *mut OstreeKernelArgs, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_kernel_args_delete( + kargs: *mut OstreeKernelArgs, + arg: *const c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_delete_key_entry( + kargs: *mut OstreeKernelArgs, + key: *const c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_free(kargs: *mut OstreeKernelArgs); + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_get_last_value( + kargs: *mut OstreeKernelArgs, + key: *const c_char, + ) -> *const c_char; + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_new_replace( + kargs: *mut OstreeKernelArgs, + arg: *const c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_parse_append(kargs: *mut OstreeKernelArgs, options: *const c_char); + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_replace(kargs: *mut OstreeKernelArgs, arg: *const c_char); + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_replace_argv(kargs: *mut OstreeKernelArgs, argv: *mut *mut c_char); + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_replace_take(kargs: *mut OstreeKernelArgs, arg: *mut c_char); + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_to_string(kargs: *mut OstreeKernelArgs) -> *mut c_char; + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_to_strv(kargs: *mut OstreeKernelArgs) -> *mut *mut c_char; + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_cleanup(loc: *mut c_void); + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_from_string(options: *const c_char) -> *mut OstreeKernelArgs; + #[cfg(any(feature = "v2019_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_3")))] + pub fn ostree_kernel_args_new() -> *mut OstreeKernelArgs; + + //========================================================================= + // OstreeRemote + //========================================================================= + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_remote_get_type() -> GType; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_remote_get_name(remote: *mut OstreeRemote) -> *const c_char; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_remote_get_url(remote: *mut OstreeRemote) -> *mut c_char; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_remote_ref(remote: *mut OstreeRemote) -> *mut OstreeRemote; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_remote_unref(remote: *mut OstreeRemote); + + //========================================================================= + // OstreeRepoCheckoutAtOptions + //========================================================================= + #[cfg(any(feature = "v2017_13", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_13")))] + pub fn ostree_repo_checkout_at_options_set_devino( + opts: *mut OstreeRepoCheckoutAtOptions, + cache: *mut OstreeRepoDevInoCache, + ); + + //========================================================================= + // OstreeRepoCommitModifier + //========================================================================= + pub fn ostree_repo_commit_modifier_get_type() -> GType; + pub fn ostree_repo_commit_modifier_new( + flags: OstreeRepoCommitModifierFlags, + commit_filter: OstreeRepoCommitFilter, + user_data: gpointer, + destroy_notify: glib::GDestroyNotify, + ) -> *mut OstreeRepoCommitModifier; + pub fn ostree_repo_commit_modifier_ref( + modifier: *mut OstreeRepoCommitModifier, + ) -> *mut OstreeRepoCommitModifier; + #[cfg(any(feature = "v2017_13", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_13")))] + pub fn ostree_repo_commit_modifier_set_devino_cache( + modifier: *mut OstreeRepoCommitModifier, + cache: *mut OstreeRepoDevInoCache, + ); + pub fn ostree_repo_commit_modifier_set_sepolicy( + modifier: *mut OstreeRepoCommitModifier, + sepolicy: *mut OstreeSePolicy, + ); + #[cfg(any(feature = "v2020_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_4")))] + pub fn ostree_repo_commit_modifier_set_sepolicy_from_commit( + modifier: *mut OstreeRepoCommitModifier, + repo: *mut OstreeRepo, + rev: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_commit_modifier_set_xattr_callback( + modifier: *mut OstreeRepoCommitModifier, + callback: OstreeRepoCommitModifierXattrCallback, + destroy: glib::GDestroyNotify, + user_data: gpointer, + ); + pub fn ostree_repo_commit_modifier_unref(modifier: *mut OstreeRepoCommitModifier); + + //========================================================================= + // OstreeRepoCommitTraverseIter + //========================================================================= + pub fn ostree_repo_commit_traverse_iter_clear(iter: *mut OstreeRepoCommitTraverseIter); + pub fn ostree_repo_commit_traverse_iter_get_dir( + iter: *mut OstreeRepoCommitTraverseIter, + out_name: *mut *mut c_char, + out_content_checksum: *mut *mut c_char, + out_meta_checksum: *mut *mut c_char, + ); + pub fn ostree_repo_commit_traverse_iter_get_file( + iter: *mut OstreeRepoCommitTraverseIter, + out_name: *mut *mut c_char, + out_checksum: *mut *mut c_char, + ); + pub fn ostree_repo_commit_traverse_iter_init_commit( + iter: *mut OstreeRepoCommitTraverseIter, + repo: *mut OstreeRepo, + commit: *mut glib::GVariant, + flags: OstreeRepoCommitTraverseFlags, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_commit_traverse_iter_init_dirtree( + iter: *mut OstreeRepoCommitTraverseIter, + repo: *mut OstreeRepo, + dirtree: *mut glib::GVariant, + flags: OstreeRepoCommitTraverseFlags, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_commit_traverse_iter_next( + iter: *mut OstreeRepoCommitTraverseIter, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> OstreeRepoCommitIterResult; + pub fn ostree_repo_commit_traverse_iter_cleanup(p: *mut c_void); + + //========================================================================= + // OstreeRepoDevInoCache + //========================================================================= + pub fn ostree_repo_devino_cache_get_type() -> GType; + pub fn ostree_repo_devino_cache_new() -> *mut OstreeRepoDevInoCache; + pub fn ostree_repo_devino_cache_ref( + cache: *mut OstreeRepoDevInoCache, + ) -> *mut OstreeRepoDevInoCache; + pub fn ostree_repo_devino_cache_unref(cache: *mut OstreeRepoDevInoCache); + + //========================================================================= + // OstreeRepoFinderResult + //========================================================================= + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_result_get_type() -> GType; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_result_new( + remote: *mut OstreeRemote, + finder: *mut OstreeRepoFinder, + priority: c_int, + ref_to_checksum: *mut glib::GHashTable, + ref_to_timestamp: *mut glib::GHashTable, + summary_last_modified: u64, + ) -> *mut OstreeRepoFinderResult; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_result_compare( + a: *const OstreeRepoFinderResult, + b: *const OstreeRepoFinderResult, + ) -> c_int; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_result_dup( + result: *mut OstreeRepoFinderResult, + ) -> *mut OstreeRepoFinderResult; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_result_free(result: *mut OstreeRepoFinderResult); + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_result_freev(results: *mut *mut OstreeRepoFinderResult); + + //========================================================================= + // OstreeRepoTransactionStats + //========================================================================= + pub fn ostree_repo_transaction_stats_get_type() -> GType; + + //========================================================================= + // OstreeAsyncProgress + //========================================================================= + pub fn ostree_async_progress_get_type() -> GType; + pub fn ostree_async_progress_new() -> *mut OstreeAsyncProgress; + pub fn ostree_async_progress_new_and_connect( + changed: *mut gpointer, + user_data: gpointer, + ) -> *mut OstreeAsyncProgress; + #[cfg(any(feature = "v2019_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_6")))] + pub fn ostree_async_progress_copy_state( + self_: *mut OstreeAsyncProgress, + dest: *mut OstreeAsyncProgress, + ); + pub fn ostree_async_progress_finish(self_: *mut OstreeAsyncProgress); + #[cfg(any(feature = "v2017_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_6")))] + pub fn ostree_async_progress_get(self_: *mut OstreeAsyncProgress, ...); + #[cfg(any(feature = "v2017_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_6")))] + pub fn ostree_async_progress_get_status(self_: *mut OstreeAsyncProgress) -> *mut c_char; + pub fn ostree_async_progress_get_uint( + self_: *mut OstreeAsyncProgress, + key: *const c_char, + ) -> c_uint; + pub fn ostree_async_progress_get_uint64( + self_: *mut OstreeAsyncProgress, + key: *const c_char, + ) -> u64; + #[cfg(any(feature = "v2017_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_6")))] + pub fn ostree_async_progress_get_variant( + self_: *mut OstreeAsyncProgress, + key: *const c_char, + ) -> *mut glib::GVariant; + #[cfg(any(feature = "v2017_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_6")))] + pub fn ostree_async_progress_set(self_: *mut OstreeAsyncProgress, ...); + #[cfg(any(feature = "v2017_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_6")))] + pub fn ostree_async_progress_set_status(self_: *mut OstreeAsyncProgress, status: *const c_char); + pub fn ostree_async_progress_set_uint( + self_: *mut OstreeAsyncProgress, + key: *const c_char, + value: c_uint, + ); + pub fn ostree_async_progress_set_uint64( + self_: *mut OstreeAsyncProgress, + key: *const c_char, + value: u64, + ); + #[cfg(any(feature = "v2017_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_6")))] + pub fn ostree_async_progress_set_variant( + self_: *mut OstreeAsyncProgress, + key: *const c_char, + value: *mut glib::GVariant, + ); + + //========================================================================= + // OstreeBootconfigParser + //========================================================================= + pub fn ostree_bootconfig_parser_get_type() -> GType; + pub fn ostree_bootconfig_parser_new() -> *mut OstreeBootconfigParser; + pub fn ostree_bootconfig_parser_clone( + self_: *mut OstreeBootconfigParser, + ) -> *mut OstreeBootconfigParser; + pub fn ostree_bootconfig_parser_get( + self_: *mut OstreeBootconfigParser, + key: *const c_char, + ) -> *const c_char; + #[cfg(any(feature = "v2020_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_7")))] + pub fn ostree_bootconfig_parser_get_overlay_initrds( + self_: *mut OstreeBootconfigParser, + ) -> *mut *mut c_char; + pub fn ostree_bootconfig_parser_parse( + self_: *mut OstreeBootconfigParser, + path: *mut gio::GFile, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_bootconfig_parser_parse_at( + self_: *mut OstreeBootconfigParser, + dfd: c_int, + path: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_bootconfig_parser_set( + self_: *mut OstreeBootconfigParser, + key: *const c_char, + value: *const c_char, + ); + #[cfg(any(feature = "v2020_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_7")))] + pub fn ostree_bootconfig_parser_set_overlay_initrds( + self_: *mut OstreeBootconfigParser, + initrds: *mut *mut c_char, + ); + pub fn ostree_bootconfig_parser_write( + self_: *mut OstreeBootconfigParser, + output: *mut gio::GFile, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_bootconfig_parser_write_at( + self_: *mut OstreeBootconfigParser, + dfd: c_int, + path: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + + //========================================================================= + // OstreeChecksumInputStream + //========================================================================= + pub fn ostree_checksum_input_stream_get_type() -> GType; + //pub fn ostree_checksum_input_stream_new(stream: *mut gio::GInputStream, checksum: *mut glib::GChecksum) -> /*Ignored*/*mut OstreeChecksumInputStream; + + //========================================================================= + // OstreeContentWriter + //========================================================================= + pub fn ostree_content_writer_get_type() -> GType; + pub fn ostree_content_writer_finish( + self_: *mut OstreeContentWriter, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> *mut c_char; + + //========================================================================= + // OstreeDeployment + //========================================================================= + pub fn ostree_deployment_get_type() -> GType; + pub fn ostree_deployment_new( + index: c_int, + osname: *const c_char, + csum: *const c_char, + deployserial: c_int, + bootcsum: *const c_char, + bootserial: c_int, + ) -> *mut OstreeDeployment; + #[cfg(any(feature = "v2018_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_3")))] + pub fn ostree_deployment_origin_remove_transient_state(origin: *mut glib::GKeyFile); + #[cfg(any(feature = "v2016_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] + pub fn ostree_deployment_unlocked_state_to_string( + state: OstreeDeploymentUnlockedState, + ) -> *const c_char; + pub fn ostree_deployment_clone(self_: *mut OstreeDeployment) -> *mut OstreeDeployment; + pub fn ostree_deployment_equal(ap: gconstpointer, bp: gconstpointer) -> gboolean; + pub fn ostree_deployment_get_bootconfig( + self_: *mut OstreeDeployment, + ) -> *mut OstreeBootconfigParser; + pub fn ostree_deployment_get_bootcsum(self_: *mut OstreeDeployment) -> *const c_char; + pub fn ostree_deployment_get_bootserial(self_: *mut OstreeDeployment) -> c_int; + pub fn ostree_deployment_get_csum(self_: *mut OstreeDeployment) -> *const c_char; + pub fn ostree_deployment_get_deployserial(self_: *mut OstreeDeployment) -> c_int; + pub fn ostree_deployment_get_index(self_: *mut OstreeDeployment) -> c_int; + pub fn ostree_deployment_get_origin(self_: *mut OstreeDeployment) -> *mut glib::GKeyFile; + pub fn ostree_deployment_get_origin_relpath(self_: *mut OstreeDeployment) -> *mut c_char; + pub fn ostree_deployment_get_osname(self_: *mut OstreeDeployment) -> *const c_char; + #[cfg(any(feature = "v2016_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] + pub fn ostree_deployment_get_unlocked( + self_: *mut OstreeDeployment, + ) -> OstreeDeploymentUnlockedState; + pub fn ostree_deployment_hash(v: gconstpointer) -> c_uint; + #[cfg(any(feature = "v2018_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_3")))] + pub fn ostree_deployment_is_pinned(self_: *mut OstreeDeployment) -> gboolean; + #[cfg(any(feature = "v2018_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_3")))] + pub fn ostree_deployment_is_staged(self_: *mut OstreeDeployment) -> gboolean; + pub fn ostree_deployment_set_bootconfig( + self_: *mut OstreeDeployment, + bootconfig: *mut OstreeBootconfigParser, + ); + pub fn ostree_deployment_set_bootserial(self_: *mut OstreeDeployment, index: c_int); + pub fn ostree_deployment_set_index(self_: *mut OstreeDeployment, index: c_int); + pub fn ostree_deployment_set_origin(self_: *mut OstreeDeployment, origin: *mut glib::GKeyFile); + + //========================================================================= + // OstreeGpgVerifyResult + //========================================================================= + pub fn ostree_gpg_verify_result_get_type() -> GType; + pub fn ostree_gpg_verify_result_describe_variant( + variant: *mut glib::GVariant, + output_buffer: *mut glib::GString, + line_prefix: *const c_char, + flags: OstreeGpgSignatureFormatFlags, + ); + pub fn ostree_gpg_verify_result_count_all(result: *mut OstreeGpgVerifyResult) -> c_uint; + pub fn ostree_gpg_verify_result_count_valid(result: *mut OstreeGpgVerifyResult) -> c_uint; + pub fn ostree_gpg_verify_result_describe( + result: *mut OstreeGpgVerifyResult, + signature_index: c_uint, + output_buffer: *mut glib::GString, + line_prefix: *const c_char, + flags: OstreeGpgSignatureFormatFlags, + ); + pub fn ostree_gpg_verify_result_get( + result: *mut OstreeGpgVerifyResult, + signature_index: c_uint, + attrs: *mut OstreeGpgSignatureAttr, + n_attrs: c_uint, + ) -> *mut glib::GVariant; + pub fn ostree_gpg_verify_result_get_all( + result: *mut OstreeGpgVerifyResult, + signature_index: c_uint, + ) -> *mut glib::GVariant; + pub fn ostree_gpg_verify_result_lookup( + result: *mut OstreeGpgVerifyResult, + key_id: *const c_char, + out_signature_index: *mut c_uint, + ) -> gboolean; + #[cfg(any(feature = "v2016_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_6")))] + pub fn ostree_gpg_verify_result_require_valid_signature( + result: *mut OstreeGpgVerifyResult, + error: *mut *mut glib::GError, + ) -> gboolean; + + //========================================================================= + // OstreeMutableTree + //========================================================================= + pub fn ostree_mutable_tree_get_type() -> GType; + pub fn ostree_mutable_tree_new() -> *mut OstreeMutableTree; + #[cfg(any(feature = "v2018_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_7")))] + pub fn ostree_mutable_tree_new_from_checksum( + repo: *mut OstreeRepo, + contents_checksum: *const c_char, + metadata_checksum: *const c_char, + ) -> *mut OstreeMutableTree; + #[cfg(any(feature = "v2021_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_5")))] + pub fn ostree_mutable_tree_new_from_commit( + repo: *mut OstreeRepo, + rev: *const c_char, + error: *mut *mut glib::GError, + ) -> *mut OstreeMutableTree; + #[cfg(any(feature = "v2018_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_7")))] + pub fn ostree_mutable_tree_check_error( + self_: *mut OstreeMutableTree, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_mutable_tree_ensure_dir( + self_: *mut OstreeMutableTree, + name: *const c_char, + out_subdir: *mut *mut OstreeMutableTree, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_mutable_tree_ensure_parent_dirs( + self_: *mut OstreeMutableTree, + split_path: *mut glib::GPtrArray, + metadata_checksum: *const c_char, + out_parent: *mut *mut OstreeMutableTree, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_7")))] + pub fn ostree_mutable_tree_fill_empty_from_dirtree( + self_: *mut OstreeMutableTree, + repo: *mut OstreeRepo, + contents_checksum: *const c_char, + metadata_checksum: *const c_char, + ) -> gboolean; + pub fn ostree_mutable_tree_get_contents_checksum( + self_: *mut OstreeMutableTree, + ) -> *const c_char; + pub fn ostree_mutable_tree_get_files(self_: *mut OstreeMutableTree) -> *mut glib::GHashTable; + pub fn ostree_mutable_tree_get_metadata_checksum( + self_: *mut OstreeMutableTree, + ) -> *const c_char; + pub fn ostree_mutable_tree_get_subdirs(self_: *mut OstreeMutableTree) -> *mut glib::GHashTable; + pub fn ostree_mutable_tree_lookup( + self_: *mut OstreeMutableTree, + name: *const c_char, + out_file_checksum: *mut *mut c_char, + out_subdir: *mut *mut OstreeMutableTree, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_9", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_9")))] + pub fn ostree_mutable_tree_remove( + self_: *mut OstreeMutableTree, + name: *const c_char, + allow_noent: gboolean, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_mutable_tree_replace_file( + self_: *mut OstreeMutableTree, + name: *const c_char, + checksum: *const c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_mutable_tree_set_contents_checksum( + self_: *mut OstreeMutableTree, + checksum: *const c_char, + ); + pub fn ostree_mutable_tree_set_metadata_checksum( + self_: *mut OstreeMutableTree, + checksum: *const c_char, + ); + pub fn ostree_mutable_tree_walk( + self_: *mut OstreeMutableTree, + split_path: *mut glib::GPtrArray, + start: c_uint, + out_subdir: *mut *mut OstreeMutableTree, + error: *mut *mut glib::GError, + ) -> gboolean; + + //========================================================================= + // OstreeRepo + //========================================================================= + pub fn ostree_repo_get_type() -> GType; + pub fn ostree_repo_new(path: *mut gio::GFile) -> *mut OstreeRepo; + pub fn ostree_repo_new_default() -> *mut OstreeRepo; + pub fn ostree_repo_new_for_sysroot_path( + repo_path: *mut gio::GFile, + sysroot_path: *mut gio::GFile, + ) -> *mut OstreeRepo; + #[cfg(any(feature = "v2017_10", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_10")))] + pub fn ostree_repo_create_at( + dfd: c_int, + path: *const c_char, + mode: OstreeRepoMode, + options: *mut glib::GVariant, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> *mut OstreeRepo; + pub fn ostree_repo_mode_from_string( + mode: *const c_char, + out_mode: *mut OstreeRepoMode, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2017_10", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_10")))] + pub fn ostree_repo_open_at( + dfd: c_int, + path: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> *mut OstreeRepo; + pub fn ostree_repo_pull_default_console_progress_changed( + progress: *mut OstreeAsyncProgress, + user_data: gpointer, + ); + #[cfg(any(feature = "v2018_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_5")))] + pub fn ostree_repo_traverse_new_parents() -> *mut glib::GHashTable; + pub fn ostree_repo_traverse_new_reachable() -> *mut glib::GHashTable; + #[cfg(any(feature = "v2018_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_5")))] + pub fn ostree_repo_traverse_parents_get_commits( + parents: *mut glib::GHashTable, + object: *mut glib::GVariant, + ) -> *mut *mut c_char; + pub fn ostree_repo_abort_transaction( + self_: *mut OstreeRepo, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_add_gpg_signature_summary( + self_: *mut OstreeRepo, + key_id: *mut *const c_char, + homedir: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_append_gpg_signature( + self_: *mut OstreeRepo, + commit_checksum: *const c_char, + signature_bytes: *mut glib::GBytes, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2016_8", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_8")))] + pub fn ostree_repo_checkout_at( + self_: *mut OstreeRepo, + options: *mut OstreeRepoCheckoutAtOptions, + destination_dfd: c_int, + destination_path: *const c_char, + commit: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_checkout_gc( + self_: *mut OstreeRepo, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_checkout_tree( + self_: *mut OstreeRepo, + mode: OstreeRepoCheckoutMode, + overwrite_mode: OstreeRepoCheckoutOverwriteMode, + destination: *mut gio::GFile, + source: *mut OstreeRepoFile, + source_info: *mut gio::GFileInfo, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_checkout_tree_at( + self_: *mut OstreeRepo, + options: *mut OstreeRepoCheckoutOptions, + destination_dfd: c_int, + destination_path: *const c_char, + commit: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_commit_transaction( + self_: *mut OstreeRepo, + out_stats: *mut OstreeRepoTransactionStats, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_copy_config(self_: *mut OstreeRepo) -> *mut glib::GKeyFile; + pub fn ostree_repo_create( + self_: *mut OstreeRepo, + mode: OstreeRepoMode, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_delete_object( + self_: *mut OstreeRepo, + objtype: OstreeObjectType, + sha256: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2017_12", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_12")))] + pub fn ostree_repo_equal(a: *mut OstreeRepo, b: *mut OstreeRepo) -> gboolean; + pub fn ostree_repo_export_tree_to_archive( + self_: *mut OstreeRepo, + opts: *mut OstreeRepoExportArchiveOptions, + root: *mut OstreeRepoFile, + archive: *mut c_void, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_find_remotes_async( + self_: *mut OstreeRepo, + refs: *const *const OstreeCollectionRef, + options: *mut glib::GVariant, + finders: *mut *mut OstreeRepoFinder, + progress: *mut OstreeAsyncProgress, + cancellable: *mut gio::GCancellable, + callback: gio::GAsyncReadyCallback, + user_data: gpointer, + ); + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_find_remotes_finish( + self_: *mut OstreeRepo, + result: *mut gio::GAsyncResult, + error: *mut *mut glib::GError, + ) -> *mut *mut OstreeRepoFinderResult; + #[cfg(any(feature = "v2017_15", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_15")))] + pub fn ostree_repo_fsck_object( + self_: *mut OstreeRepo, + objtype: OstreeObjectType, + sha256: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2019_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_2")))] + pub fn ostree_repo_get_bootloader(self_: *mut OstreeRepo) -> *const c_char; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_get_collection_id(self_: *mut OstreeRepo) -> *const c_char; + pub fn ostree_repo_get_config(self_: *mut OstreeRepo) -> *mut glib::GKeyFile; + #[cfg(any(feature = "v2018_9", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_9")))] + pub fn ostree_repo_get_default_repo_finders(self_: *mut OstreeRepo) -> *const *const c_char; + #[cfg(any(feature = "v2016_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] + pub fn ostree_repo_get_dfd(self_: *mut OstreeRepo) -> c_int; + pub fn ostree_repo_get_disable_fsync(self_: *mut OstreeRepo) -> gboolean; + #[cfg(any(feature = "v2018_9", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_9")))] + pub fn ostree_repo_get_min_free_space_bytes( + self_: *mut OstreeRepo, + out_reserved_bytes: *mut u64, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_get_mode(self_: *mut OstreeRepo) -> OstreeRepoMode; + pub fn ostree_repo_get_parent(self_: *mut OstreeRepo) -> *mut OstreeRepo; + pub fn ostree_repo_get_path(self_: *mut OstreeRepo) -> *mut gio::GFile; + #[cfg(any(feature = "v2016_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_5")))] + pub fn ostree_repo_get_remote_boolean_option( + self_: *mut OstreeRepo, + remote_name: *const c_char, + option_name: *const c_char, + default_value: gboolean, + out_value: *mut gboolean, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2016_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_5")))] + pub fn ostree_repo_get_remote_list_option( + self_: *mut OstreeRepo, + remote_name: *const c_char, + option_name: *const c_char, + out_value: *mut *mut *mut c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2016_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_5")))] + pub fn ostree_repo_get_remote_option( + self_: *mut OstreeRepo, + remote_name: *const c_char, + option_name: *const c_char, + default_value: *const c_char, + out_value: *mut *mut c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_8", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_8")))] + pub fn ostree_repo_gpg_sign_data( + self_: *mut OstreeRepo, + data: *mut glib::GBytes, + old_signatures: *mut glib::GBytes, + key_id: *mut *const c_char, + homedir: *const c_char, + out_signatures: *mut *mut glib::GBytes, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2016_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_6")))] + pub fn ostree_repo_gpg_verify_data( + self_: *mut OstreeRepo, + remote_name: *const c_char, + data: *mut glib::GBytes, + signatures: *mut glib::GBytes, + keyringdir: *mut gio::GFile, + extra_keyring: *mut gio::GFile, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> *mut OstreeGpgVerifyResult; + pub fn ostree_repo_has_object( + self_: *mut OstreeRepo, + objtype: OstreeObjectType, + checksum: *const c_char, + out_have_object: *mut gboolean, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2017_12", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_12")))] + pub fn ostree_repo_hash(self_: *mut OstreeRepo) -> c_uint; + pub fn ostree_repo_import_archive_to_mtree( + self_: *mut OstreeRepo, + opts: *mut OstreeRepoImportArchiveOptions, + archive: *mut c_void, + mtree: *mut OstreeMutableTree, + modifier: *mut OstreeRepoCommitModifier, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_import_object_from( + self_: *mut OstreeRepo, + source: *mut OstreeRepo, + objtype: OstreeObjectType, + checksum: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2016_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_5")))] + pub fn ostree_repo_import_object_from_with_trust( + self_: *mut OstreeRepo, + source: *mut OstreeRepo, + objtype: OstreeObjectType, + checksum: *const c_char, + trusted: gboolean, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_is_system(repo: *mut OstreeRepo) -> gboolean; + pub fn ostree_repo_is_writable( + self_: *mut OstreeRepo, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_list_collection_refs( + self_: *mut OstreeRepo, + match_collection_id: *const c_char, + out_all_refs: *mut *mut glib::GHashTable, + flags: OstreeRepoListRefsExtFlags, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_list_commit_objects_starting_with( + self_: *mut OstreeRepo, + start: *const c_char, + out_commits: *mut *mut glib::GHashTable, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_list_objects( + self_: *mut OstreeRepo, + flags: OstreeRepoListObjectsFlags, + out_objects: *mut *mut glib::GHashTable, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_list_refs( + self_: *mut OstreeRepo, + refspec_prefix: *const c_char, + out_all_refs: *mut *mut glib::GHashTable, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2016_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] + pub fn ostree_repo_list_refs_ext( + self_: *mut OstreeRepo, + refspec_prefix: *const c_char, + out_all_refs: *mut *mut glib::GHashTable, + flags: OstreeRepoListRefsExtFlags, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_8", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_8")))] + pub fn ostree_repo_list_static_delta_indexes( + self_: *mut OstreeRepo, + out_indexes: *mut *mut glib::GPtrArray, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_list_static_delta_names( + self_: *mut OstreeRepo, + out_deltas: *mut *mut glib::GPtrArray, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2015_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2015_7")))] + pub fn ostree_repo_load_commit( + self_: *mut OstreeRepo, + checksum: *const c_char, + out_commit: *mut *mut glib::GVariant, + out_state: *mut OstreeRepoCommitState, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_load_file( + self_: *mut OstreeRepo, + checksum: *const c_char, + out_input: *mut *mut gio::GInputStream, + out_file_info: *mut *mut gio::GFileInfo, + out_xattrs: *mut *mut glib::GVariant, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_load_object_stream( + self_: *mut OstreeRepo, + objtype: OstreeObjectType, + checksum: *const c_char, + out_input: *mut *mut gio::GInputStream, + out_size: *mut u64, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_load_variant( + self_: *mut OstreeRepo, + objtype: OstreeObjectType, + sha256: *const c_char, + out_variant: *mut *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_load_variant_if_exists( + self_: *mut OstreeRepo, + objtype: OstreeObjectType, + sha256: *const c_char, + out_variant: *mut *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2021_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_3")))] + pub fn ostree_repo_lock_pop( + self_: *mut OstreeRepo, + lock_type: OstreeRepoLockType, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2021_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_3")))] + pub fn ostree_repo_lock_push( + self_: *mut OstreeRepo, + lock_type: OstreeRepoLockType, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2017_15", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_15")))] + pub fn ostree_repo_mark_commit_partial( + self_: *mut OstreeRepo, + checksum: *const c_char, + is_partial: gboolean, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2019_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2019_4")))] + pub fn ostree_repo_mark_commit_partial_reason( + self_: *mut OstreeRepo, + checksum: *const c_char, + is_partial: gboolean, + in_state: OstreeRepoCommitState, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_open( + self_: *mut OstreeRepo, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_prepare_transaction( + self_: *mut OstreeRepo, + out_transaction_resume: *mut gboolean, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_prune( + self_: *mut OstreeRepo, + flags: OstreeRepoPruneFlags, + depth: c_int, + out_objects_total: *mut c_int, + out_objects_pruned: *mut c_int, + out_pruned_object_size_total: *mut u64, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2017_1", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_1")))] + pub fn ostree_repo_prune_from_reachable( + self_: *mut OstreeRepo, + options: *mut OstreeRepoPruneOptions, + out_objects_total: *mut c_int, + out_objects_pruned: *mut c_int, + out_pruned_object_size_total: *mut u64, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_prune_static_deltas( + self_: *mut OstreeRepo, + commit: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_pull( + self_: *mut OstreeRepo, + remote_name: *const c_char, + refs_to_fetch: *mut *mut c_char, + flags: OstreeRepoPullFlags, + progress: *mut OstreeAsyncProgress, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_pull_from_remotes_async( + self_: *mut OstreeRepo, + results: *const *const OstreeRepoFinderResult, + options: *mut glib::GVariant, + progress: *mut OstreeAsyncProgress, + cancellable: *mut gio::GCancellable, + callback: gio::GAsyncReadyCallback, + user_data: gpointer, + ); + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_pull_from_remotes_finish( + self_: *mut OstreeRepo, + result: *mut gio::GAsyncResult, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_pull_one_dir( + self_: *mut OstreeRepo, + remote_name: *const c_char, + dir_to_pull: *const c_char, + refs_to_fetch: *mut *mut c_char, + flags: OstreeRepoPullFlags, + progress: *mut OstreeAsyncProgress, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_pull_with_options( + self_: *mut OstreeRepo, + remote_name_or_baseurl: *const c_char, + options: *mut glib::GVariant, + progress: *mut OstreeAsyncProgress, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_query_object_storage_size( + self_: *mut OstreeRepo, + objtype: OstreeObjectType, + sha256: *const c_char, + out_size: *mut u64, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_read_commit( + self_: *mut OstreeRepo, + ref_: *const c_char, + out_root: *mut *mut gio::GFile, + out_commit: *mut *mut c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_read_commit_detached_metadata( + self_: *mut OstreeRepo, + checksum: *const c_char, + out_metadata: *mut *mut glib::GVariant, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_regenerate_summary( + self_: *mut OstreeRepo, + additional_metadata: *mut glib::GVariant, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2017_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_2")))] + pub fn ostree_repo_reload_config( + self_: *mut OstreeRepo, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_remote_add( + self_: *mut OstreeRepo, + name: *const c_char, + url: *const c_char, + options: *mut glib::GVariant, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_remote_change( + self_: *mut OstreeRepo, + sysroot: *mut gio::GFile, + changeop: OstreeRepoRemoteChange, + name: *const c_char, + url: *const c_char, + options: *mut glib::GVariant, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_remote_delete( + self_: *mut OstreeRepo, + name: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_remote_fetch_summary( + self_: *mut OstreeRepo, + name: *const c_char, + out_summary: *mut *mut glib::GBytes, + out_signatures: *mut *mut glib::GBytes, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2016_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_6")))] + pub fn ostree_repo_remote_fetch_summary_with_options( + self_: *mut OstreeRepo, + name: *const c_char, + options: *mut glib::GVariant, + out_summary: *mut *mut glib::GBytes, + out_signatures: *mut *mut glib::GBytes, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2021_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_4")))] + pub fn ostree_repo_remote_get_gpg_keys( + self_: *mut OstreeRepo, + name: *const c_char, + key_ids: *const *const c_char, + out_keys: *mut *mut glib::GPtrArray, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_remote_get_gpg_verify( + self_: *mut OstreeRepo, + name: *const c_char, + out_gpg_verify: *mut gboolean, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_remote_get_gpg_verify_summary( + self_: *mut OstreeRepo, + name: *const c_char, + out_gpg_verify_summary: *mut gboolean, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_remote_get_url( + self_: *mut OstreeRepo, + name: *const c_char, + out_url: *mut *mut c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_remote_gpg_import( + self_: *mut OstreeRepo, + name: *const c_char, + source_stream: *mut gio::GInputStream, + key_ids: *const *const c_char, + out_imported: *mut c_uint, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_remote_list( + self_: *mut OstreeRepo, + out_n_remotes: *mut c_uint, + ) -> *mut *mut c_char; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_remote_list_collection_refs( + self_: *mut OstreeRepo, + remote_name: *const c_char, + out_all_refs: *mut *mut glib::GHashTable, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_remote_list_refs( + self_: *mut OstreeRepo, + remote_name: *const c_char, + out_all_refs: *mut *mut glib::GHashTable, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_resolve_collection_ref( + self_: *mut OstreeRepo, + ref_: *const OstreeCollectionRef, + allow_noent: gboolean, + flags: OstreeRepoResolveRevExtFlags, + out_rev: *mut *mut c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_resolve_keyring_for_collection( + self_: *mut OstreeRepo, + collection_id: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> *mut OstreeRemote; + pub fn ostree_repo_resolve_rev( + self_: *mut OstreeRepo, + refspec: *const c_char, + allow_noent: gboolean, + out_rev: *mut *mut c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2016_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_7")))] + pub fn ostree_repo_resolve_rev_ext( + self_: *mut OstreeRepo, + refspec: *const c_char, + allow_noent: gboolean, + flags: OstreeRepoResolveRevExtFlags, + out_rev: *mut *mut c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_scan_hardlinks( + self_: *mut OstreeRepo, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2017_10", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_10")))] + pub fn ostree_repo_set_alias_ref_immediate( + self_: *mut OstreeRepo, + remote: *const c_char, + ref_: *const c_char, + target: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2016_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_5")))] + pub fn ostree_repo_set_cache_dir( + self_: *mut OstreeRepo, + dfd: c_int, + path: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_set_collection_id( + self_: *mut OstreeRepo, + collection_id: *const c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_set_collection_ref_immediate( + self_: *mut OstreeRepo, + ref_: *const OstreeCollectionRef, + checksum: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_set_disable_fsync(self_: *mut OstreeRepo, disable_fsync: gboolean); + pub fn ostree_repo_set_ref_immediate( + self_: *mut OstreeRepo, + remote: *const c_char, + ref_: *const c_char, + checksum: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_sign_commit( + self_: *mut OstreeRepo, + commit_checksum: *const c_char, + key_id: *const c_char, + homedir: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_sign_delta( + self_: *mut OstreeRepo, + from_commit: *const c_char, + to_commit: *const c_char, + key_id: *const c_char, + homedir: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2021_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_4")))] + pub fn ostree_repo_signature_verify_commit_data( + self_: *mut OstreeRepo, + remote_name: *const c_char, + commit_data: *mut glib::GBytes, + commit_metadata: *mut glib::GBytes, + flags: OstreeRepoVerifyFlags, + out_results: *mut *mut c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_static_delta_execute_offline( + self_: *mut OstreeRepo, + dir_or_file: *mut gio::GFile, + skip_validation: gboolean, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_7")))] + pub fn ostree_repo_static_delta_execute_offline_with_signature( + self_: *mut OstreeRepo, + dir_or_file: *mut gio::GFile, + sign: *mut OstreeSign, + skip_validation: gboolean, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_static_delta_generate( + self_: *mut OstreeRepo, + opt: OstreeStaticDeltaGenerateOpt, + from: *const c_char, + to: *const c_char, + metadata: *mut glib::GVariant, + params: *mut glib::GVariant, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_8", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_8")))] + pub fn ostree_repo_static_delta_reindex( + repo: *mut OstreeRepo, + flags: OstreeStaticDeltaIndexFlags, + opt_to_commit: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_7")))] + pub fn ostree_repo_static_delta_verify_signature( + self_: *mut OstreeRepo, + delta_id: *const c_char, + sign: *mut OstreeSign, + out_success_message: *mut *mut c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_transaction_set_collection_ref( + self_: *mut OstreeRepo, + ref_: *const OstreeCollectionRef, + checksum: *const c_char, + ); + pub fn ostree_repo_transaction_set_ref( + self_: *mut OstreeRepo, + remote: *const c_char, + ref_: *const c_char, + checksum: *const c_char, + ); + pub fn ostree_repo_transaction_set_refspec( + self_: *mut OstreeRepo, + refspec: *const c_char, + checksum: *const c_char, + ); + pub fn ostree_repo_traverse_commit( + repo: *mut OstreeRepo, + commit_checksum: *const c_char, + maxdepth: c_int, + out_reachable: *mut *mut glib::GHashTable, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_traverse_commit_union( + repo: *mut OstreeRepo, + commit_checksum: *const c_char, + maxdepth: c_int, + inout_reachable: *mut glib::GHashTable, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_5")))] + pub fn ostree_repo_traverse_commit_union_with_parents( + repo: *mut OstreeRepo, + commit_checksum: *const c_char, + maxdepth: c_int, + inout_reachable: *mut glib::GHashTable, + inout_parents: *mut glib::GHashTable, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_5")))] + pub fn ostree_repo_traverse_commit_with_flags( + repo: *mut OstreeRepo, + flags: OstreeRepoCommitTraverseFlags, + commit_checksum: *const c_char, + maxdepth: c_int, + inout_reachable: *mut glib::GHashTable, + inout_parents: *mut glib::GHashTable, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_traverse_reachable_refs( + self_: *mut OstreeRepo, + depth: c_uint, + reachable: *mut glib::GHashTable, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_verify_commit( + self_: *mut OstreeRepo, + commit_checksum: *const c_char, + keyringdir: *mut gio::GFile, + extra_keyring: *mut gio::GFile, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_verify_commit_ext( + self_: *mut OstreeRepo, + commit_checksum: *const c_char, + keyringdir: *mut gio::GFile, + extra_keyring: *mut gio::GFile, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> *mut OstreeGpgVerifyResult; + #[cfg(any(feature = "v2016_14", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_14")))] + pub fn ostree_repo_verify_commit_for_remote( + self_: *mut OstreeRepo, + commit_checksum: *const c_char, + remote_name: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> *mut OstreeGpgVerifyResult; + pub fn ostree_repo_verify_summary( + self_: *mut OstreeRepo, + remote_name: *const c_char, + summary: *mut glib::GBytes, + signatures: *mut glib::GBytes, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> *mut OstreeGpgVerifyResult; + pub fn ostree_repo_write_archive_to_mtree( + self_: *mut OstreeRepo, + archive: *mut gio::GFile, + mtree: *mut OstreeMutableTree, + modifier: *mut OstreeRepoCommitModifier, + autocreate_parents: gboolean, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_write_archive_to_mtree_from_fd( + self_: *mut OstreeRepo, + fd: c_int, + mtree: *mut OstreeMutableTree, + modifier: *mut OstreeRepoCommitModifier, + autocreate_parents: gboolean, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_write_commit( + self_: *mut OstreeRepo, + parent: *const c_char, + subject: *const c_char, + body: *const c_char, + metadata: *mut glib::GVariant, + root: *mut OstreeRepoFile, + out_commit: *mut *mut c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_write_commit_detached_metadata( + self_: *mut OstreeRepo, + checksum: *const c_char, + metadata: *mut glib::GVariant, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_write_commit_with_time( + self_: *mut OstreeRepo, + parent: *const c_char, + subject: *const c_char, + body: *const c_char, + metadata: *mut glib::GVariant, + root: *mut OstreeRepoFile, + time: u64, + out_commit: *mut *mut c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_write_config( + self_: *mut OstreeRepo, + new_config: *mut glib::GKeyFile, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_write_content( + self_: *mut OstreeRepo, + expected_checksum: *const c_char, + object_input: *mut gio::GInputStream, + length: u64, + out_csum: *mut *mut [*mut u8; 32], + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_write_content_async( + self_: *mut OstreeRepo, + expected_checksum: *const c_char, + object: *mut gio::GInputStream, + length: u64, + cancellable: *mut gio::GCancellable, + callback: gio::GAsyncReadyCallback, + user_data: gpointer, + ); + pub fn ostree_repo_write_content_finish( + self_: *mut OstreeRepo, + result: *mut gio::GAsyncResult, + out_csum: *mut *mut u8, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_write_content_trusted( + self_: *mut OstreeRepo, + checksum: *const c_char, + object_input: *mut gio::GInputStream, + length: u64, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_write_dfd_to_mtree( + self_: *mut OstreeRepo, + dfd: c_int, + path: *const c_char, + mtree: *mut OstreeMutableTree, + modifier: *mut OstreeRepoCommitModifier, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_write_directory_to_mtree( + self_: *mut OstreeRepo, + dir: *mut gio::GFile, + mtree: *mut OstreeMutableTree, + modifier: *mut OstreeRepoCommitModifier, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_write_metadata( + self_: *mut OstreeRepo, + objtype: OstreeObjectType, + expected_checksum: *const c_char, + object: *mut glib::GVariant, + out_csum: *mut *mut [*mut u8; 32], + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_write_metadata_async( + self_: *mut OstreeRepo, + objtype: OstreeObjectType, + expected_checksum: *const c_char, + object: *mut glib::GVariant, + cancellable: *mut gio::GCancellable, + callback: gio::GAsyncReadyCallback, + user_data: gpointer, + ); + pub fn ostree_repo_write_metadata_finish( + self_: *mut OstreeRepo, + result: *mut gio::GAsyncResult, + out_csum: *mut *mut [c_uchar; 32], + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_write_metadata_stream_trusted( + self_: *mut OstreeRepo, + objtype: OstreeObjectType, + checksum: *const c_char, + object_input: *mut gio::GInputStream, + length: u64, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_write_metadata_trusted( + self_: *mut OstreeRepo, + objtype: OstreeObjectType, + checksum: *const c_char, + variant: *mut glib::GVariant, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_write_mtree( + self_: *mut OstreeRepo, + mtree: *mut OstreeMutableTree, + out_file: *mut *mut gio::GFile, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2021_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_2")))] + pub fn ostree_repo_write_regfile( + self_: *mut OstreeRepo, + expected_checksum: *const c_char, + uid: u32, + gid: u32, + mode: u32, + content_len: u64, + xattrs: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> *mut OstreeContentWriter; + #[cfg(any(feature = "v2021_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_2")))] + pub fn ostree_repo_write_regfile_inline( + self_: *mut OstreeRepo, + expected_checksum: *const c_char, + uid: u32, + gid: u32, + mode: u32, + xattrs: *mut glib::GVariant, + buf: *const u8, + len: size_t, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> *mut c_char; + #[cfg(any(feature = "v2021_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_2")))] + pub fn ostree_repo_write_symlink( + self_: *mut OstreeRepo, + expected_checksum: *const c_char, + uid: u32, + gid: u32, + xattrs: *mut glib::GVariant, + symlink_target: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> *mut c_char; + + //========================================================================= + // OstreeRepoFile + //========================================================================= + pub fn ostree_repo_file_get_type() -> GType; + pub fn ostree_repo_file_ensure_resolved( + self_: *mut OstreeRepoFile, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_file_get_checksum(self_: *mut OstreeRepoFile) -> *const c_char; + pub fn ostree_repo_file_get_repo(self_: *mut OstreeRepoFile) -> *mut OstreeRepo; + pub fn ostree_repo_file_get_root(self_: *mut OstreeRepoFile) -> *mut OstreeRepoFile; + pub fn ostree_repo_file_get_xattrs( + self_: *mut OstreeRepoFile, + out_xattrs: *mut *mut glib::GVariant, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_file_tree_find_child( + self_: *mut OstreeRepoFile, + name: *const c_char, + is_dir: *mut gboolean, + out_container: *mut *mut glib::GVariant, + ) -> c_int; + pub fn ostree_repo_file_tree_get_contents(self_: *mut OstreeRepoFile) -> *mut glib::GVariant; + pub fn ostree_repo_file_tree_get_contents_checksum(self_: *mut OstreeRepoFile) + -> *const c_char; + pub fn ostree_repo_file_tree_get_metadata(self_: *mut OstreeRepoFile) -> *mut glib::GVariant; + pub fn ostree_repo_file_tree_get_metadata_checksum(self_: *mut OstreeRepoFile) + -> *const c_char; + pub fn ostree_repo_file_tree_query_child( + self_: *mut OstreeRepoFile, + n: c_int, + attributes: *const c_char, + flags: gio::GFileQueryInfoFlags, + out_info: *mut *mut gio::GFileInfo, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_repo_file_tree_set_metadata( + self_: *mut OstreeRepoFile, + checksum: *const c_char, + metadata: *mut glib::GVariant, + ); + + //========================================================================= + // OstreeRepoFinderAvahi + //========================================================================= + pub fn ostree_repo_finder_avahi_get_type() -> GType; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_avahi_new( + context: *mut glib::GMainContext, + ) -> *mut OstreeRepoFinderAvahi; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_avahi_start( + self_: *mut OstreeRepoFinderAvahi, + error: *mut *mut glib::GError, + ); + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_avahi_stop(self_: *mut OstreeRepoFinderAvahi); + + //========================================================================= + // OstreeRepoFinderConfig + //========================================================================= + pub fn ostree_repo_finder_config_get_type() -> GType; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_config_new() -> *mut OstreeRepoFinderConfig; + + //========================================================================= + // OstreeRepoFinderMount + //========================================================================= + pub fn ostree_repo_finder_mount_get_type() -> GType; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_mount_new( + monitor: *mut gio::GVolumeMonitor, + ) -> *mut OstreeRepoFinderMount; + + //========================================================================= + // OstreeRepoFinderOverride + //========================================================================= + pub fn ostree_repo_finder_override_get_type() -> GType; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_override_new() -> *mut OstreeRepoFinderOverride; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_override_add_uri( + self_: *mut OstreeRepoFinderOverride, + uri: *const c_char, + ); + + //========================================================================= + // OstreeSePolicy + //========================================================================= + pub fn ostree_sepolicy_get_type() -> GType; + pub fn ostree_sepolicy_new( + path: *mut gio::GFile, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> *mut OstreeSePolicy; + #[cfg(any(feature = "v2017_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_4")))] + pub fn ostree_sepolicy_new_at( + rootfs_dfd: c_int, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> *mut OstreeSePolicy; + pub fn ostree_sepolicy_new_from_commit( + repo: *mut OstreeRepo, + rev: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> *mut OstreeSePolicy; + pub fn ostree_sepolicy_fscreatecon_cleanup(unused: *mut *mut c_void); + #[cfg(any(feature = "v2016_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_5")))] + pub fn ostree_sepolicy_get_csum(self_: *mut OstreeSePolicy) -> *const c_char; + pub fn ostree_sepolicy_get_label( + self_: *mut OstreeSePolicy, + relpath: *const c_char, + unix_mode: u32, + out_label: *mut *mut c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sepolicy_get_name(self_: *mut OstreeSePolicy) -> *const c_char; + pub fn ostree_sepolicy_get_path(self_: *mut OstreeSePolicy) -> *mut gio::GFile; + pub fn ostree_sepolicy_restorecon( + self_: *mut OstreeSePolicy, + path: *const c_char, + info: *mut gio::GFileInfo, + target: *mut gio::GFile, + flags: OstreeSePolicyRestoreconFlags, + out_new_label: *mut *mut c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sepolicy_setfscreatecon( + self_: *mut OstreeSePolicy, + path: *const c_char, + mode: u32, + error: *mut *mut glib::GError, + ) -> gboolean; + + //========================================================================= + // OstreeSysroot + //========================================================================= + pub fn ostree_sysroot_get_type() -> GType; + pub fn ostree_sysroot_new(path: *mut gio::GFile) -> *mut OstreeSysroot; + pub fn ostree_sysroot_new_default() -> *mut OstreeSysroot; + pub fn ostree_sysroot_get_deployment_origin_path( + deployment_path: *mut gio::GFile, + ) -> *mut gio::GFile; + pub fn ostree_sysroot_cleanup( + self_: *mut OstreeSysroot, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_sysroot_cleanup_prune_repo( + sysroot: *mut OstreeSysroot, + options: *mut OstreeRepoPruneOptions, + out_objects_total: *mut c_int, + out_objects_pruned: *mut c_int, + out_pruned_object_size_total: *mut u64, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_5")))] + pub fn ostree_sysroot_deploy_tree( + self_: *mut OstreeSysroot, + osname: *const c_char, + revision: *const c_char, + origin: *mut glib::GKeyFile, + provided_merge_deployment: *mut OstreeDeployment, + override_kernel_argv: *mut *mut c_char, + out_new_deployment: *mut *mut OstreeDeployment, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_7")))] + pub fn ostree_sysroot_deploy_tree_with_options( + self_: *mut OstreeSysroot, + osname: *const c_char, + revision: *const c_char, + origin: *mut glib::GKeyFile, + provided_merge_deployment: *mut OstreeDeployment, + opts: *mut OstreeSysrootDeployTreeOpts, + out_new_deployment: *mut *mut OstreeDeployment, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sysroot_deployment_set_kargs( + self_: *mut OstreeSysroot, + deployment: *mut OstreeDeployment, + new_kargs: *mut *mut c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sysroot_deployment_set_mutable( + self_: *mut OstreeSysroot, + deployment: *mut OstreeDeployment, + is_mutable: gboolean, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_3")))] + pub fn ostree_sysroot_deployment_set_pinned( + self_: *mut OstreeSysroot, + deployment: *mut OstreeDeployment, + is_pinned: gboolean, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2016_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] + pub fn ostree_sysroot_deployment_unlock( + self_: *mut OstreeSysroot, + deployment: *mut OstreeDeployment, + unlocked_state: OstreeDeploymentUnlockedState, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sysroot_ensure_initialized( + self_: *mut OstreeSysroot, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sysroot_get_booted_deployment(self_: *mut OstreeSysroot) + -> *mut OstreeDeployment; + pub fn ostree_sysroot_get_bootversion(self_: *mut OstreeSysroot) -> c_int; + pub fn ostree_sysroot_get_deployment_directory( + self_: *mut OstreeSysroot, + deployment: *mut OstreeDeployment, + ) -> *mut gio::GFile; + pub fn ostree_sysroot_get_deployment_dirpath( + self_: *mut OstreeSysroot, + deployment: *mut OstreeDeployment, + ) -> *mut c_char; + pub fn ostree_sysroot_get_deployments(self_: *mut OstreeSysroot) -> *mut glib::GPtrArray; + pub fn ostree_sysroot_get_fd(self_: *mut OstreeSysroot) -> c_int; + pub fn ostree_sysroot_get_merge_deployment( + self_: *mut OstreeSysroot, + osname: *const c_char, + ) -> *mut OstreeDeployment; + pub fn ostree_sysroot_get_path(self_: *mut OstreeSysroot) -> *mut gio::GFile; + pub fn ostree_sysroot_get_repo( + self_: *mut OstreeSysroot, + out_repo: *mut *mut OstreeRepo, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_5")))] + pub fn ostree_sysroot_get_staged_deployment(self_: *mut OstreeSysroot) + -> *mut OstreeDeployment; + pub fn ostree_sysroot_get_subbootversion(self_: *mut OstreeSysroot) -> c_int; + #[cfg(any(feature = "v2016_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] + pub fn ostree_sysroot_init_osname( + self_: *mut OstreeSysroot, + osname: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_1", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_1")))] + pub fn ostree_sysroot_initialize( + self_: *mut OstreeSysroot, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_1", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_1")))] + pub fn ostree_sysroot_is_booted(self_: *mut OstreeSysroot) -> gboolean; + pub fn ostree_sysroot_load( + self_: *mut OstreeSysroot, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2016_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_4")))] + pub fn ostree_sysroot_load_if_changed( + self_: *mut OstreeSysroot, + out_changed: *mut gboolean, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sysroot_lock( + self_: *mut OstreeSysroot, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sysroot_lock_async( + self_: *mut OstreeSysroot, + cancellable: *mut gio::GCancellable, + callback: gio::GAsyncReadyCallback, + user_data: gpointer, + ); + pub fn ostree_sysroot_lock_finish( + self_: *mut OstreeSysroot, + result: *mut gio::GAsyncResult, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sysroot_origin_new_from_refspec( + self_: *mut OstreeSysroot, + refspec: *const c_char, + ) -> *mut glib::GKeyFile; + pub fn ostree_sysroot_prepare_cleanup( + self_: *mut OstreeSysroot, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2017_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_7")))] + pub fn ostree_sysroot_query_deployments_for( + self_: *mut OstreeSysroot, + osname: *const c_char, + out_pending: *mut *mut OstreeDeployment, + out_rollback: *mut *mut OstreeDeployment, + ); + #[cfg(any(feature = "v2017_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_7")))] + pub fn ostree_sysroot_repo(self_: *mut OstreeSysroot) -> *mut OstreeRepo; + #[cfg(any(feature = "v2021_1", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_1")))] + pub fn ostree_sysroot_require_booted_deployment( + self_: *mut OstreeSysroot, + error: *mut *mut glib::GError, + ) -> *mut OstreeDeployment; + #[cfg(any(feature = "v2020_1", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_1")))] + pub fn ostree_sysroot_set_mount_namespace_in_use(self_: *mut OstreeSysroot); + pub fn ostree_sysroot_simple_write_deployment( + sysroot: *mut OstreeSysroot, + osname: *const c_char, + new_deployment: *mut OstreeDeployment, + merge_deployment: *mut OstreeDeployment, + flags: OstreeSysrootSimpleWriteDeploymentFlags, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_7")))] + pub fn ostree_sysroot_stage_overlay_initrd( + self_: *mut OstreeSysroot, + fd: c_int, + out_checksum: *mut *mut c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_5", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_5")))] + pub fn ostree_sysroot_stage_tree( + self_: *mut OstreeSysroot, + osname: *const c_char, + revision: *const c_char, + origin: *mut glib::GKeyFile, + merge_deployment: *mut OstreeDeployment, + override_kernel_argv: *mut *mut c_char, + out_new_deployment: *mut *mut OstreeDeployment, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_7", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_7")))] + pub fn ostree_sysroot_stage_tree_with_options( + self_: *mut OstreeSysroot, + osname: *const c_char, + revision: *const c_char, + origin: *mut glib::GKeyFile, + merge_deployment: *mut OstreeDeployment, + opts: *mut OstreeSysrootDeployTreeOpts, + out_new_deployment: *mut *mut OstreeDeployment, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sysroot_try_lock( + self_: *mut OstreeSysroot, + out_acquired: *mut gboolean, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sysroot_unload(self_: *mut OstreeSysroot); + pub fn ostree_sysroot_unlock(self_: *mut OstreeSysroot); + pub fn ostree_sysroot_write_deployments( + self_: *mut OstreeSysroot, + new_deployments: *mut glib::GPtrArray, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2017_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_4")))] + pub fn ostree_sysroot_write_deployments_with_options( + self_: *mut OstreeSysroot, + new_deployments: *mut glib::GPtrArray, + opts: *mut OstreeSysrootWriteDeploymentsOpts, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sysroot_write_origin_file( + sysroot: *mut OstreeSysroot, + deployment: *mut OstreeDeployment, + new_origin: *mut glib::GKeyFile, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + + //========================================================================= + // OstreeSysrootUpgrader + //========================================================================= + pub fn ostree_sysroot_upgrader_get_type() -> GType; + pub fn ostree_sysroot_upgrader_new( + sysroot: *mut OstreeSysroot, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> *mut OstreeSysrootUpgrader; + pub fn ostree_sysroot_upgrader_new_for_os( + sysroot: *mut OstreeSysroot, + osname: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> *mut OstreeSysrootUpgrader; + pub fn ostree_sysroot_upgrader_new_for_os_with_flags( + sysroot: *mut OstreeSysroot, + osname: *const c_char, + flags: OstreeSysrootUpgraderFlags, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> *mut OstreeSysrootUpgrader; + pub fn ostree_sysroot_upgrader_check_timestamps( + repo: *mut OstreeRepo, + from_rev: *const c_char, + to_rev: *const c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sysroot_upgrader_deploy( + self_: *mut OstreeSysrootUpgrader, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sysroot_upgrader_dup_origin( + self_: *mut OstreeSysrootUpgrader, + ) -> *mut glib::GKeyFile; + pub fn ostree_sysroot_upgrader_get_origin( + self_: *mut OstreeSysrootUpgrader, + ) -> *mut glib::GKeyFile; + pub fn ostree_sysroot_upgrader_get_origin_description( + self_: *mut OstreeSysrootUpgrader, + ) -> *mut c_char; + pub fn ostree_sysroot_upgrader_pull( + self_: *mut OstreeSysrootUpgrader, + flags: OstreeRepoPullFlags, + upgrader_flags: OstreeSysrootUpgraderPullFlags, + progress: *mut OstreeAsyncProgress, + out_changed: *mut gboolean, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sysroot_upgrader_pull_one_dir( + self_: *mut OstreeSysrootUpgrader, + dir_to_pull: *const c_char, + flags: OstreeRepoPullFlags, + upgrader_flags: OstreeSysrootUpgraderPullFlags, + progress: *mut OstreeAsyncProgress, + out_changed: *mut gboolean, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sysroot_upgrader_set_origin( + self_: *mut OstreeSysrootUpgrader, + origin: *mut glib::GKeyFile, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + + //========================================================================= + // OstreeRepoFinder + //========================================================================= + pub fn ostree_repo_finder_get_type() -> GType; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_resolve_all_async( + finders: *const *mut OstreeRepoFinder, + refs: *const *const OstreeCollectionRef, + parent_repo: *mut OstreeRepo, + cancellable: *mut gio::GCancellable, + callback: gio::GAsyncReadyCallback, + user_data: gpointer, + ); + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_resolve_all_finish( + result: *mut gio::GAsyncResult, + error: *mut *mut glib::GError, + ) -> *mut glib::GPtrArray; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_resolve_async( + self_: *mut OstreeRepoFinder, + refs: *const *const OstreeCollectionRef, + parent_repo: *mut OstreeRepo, + cancellable: *mut gio::GCancellable, + callback: gio::GAsyncReadyCallback, + user_data: gpointer, + ); + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_repo_finder_resolve_finish( + self_: *mut OstreeRepoFinder, + result: *mut gio::GAsyncResult, + error: *mut *mut glib::GError, + ) -> *mut glib::GPtrArray; + + //========================================================================= + // OstreeSign + //========================================================================= + pub fn ostree_sign_get_type() -> GType; + #[cfg(any(feature = "v2020_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] + pub fn ostree_sign_get_all() -> *mut glib::GPtrArray; + #[cfg(any(feature = "v2020_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] + pub fn ostree_sign_get_by_name( + name: *const c_char, + error: *mut *mut glib::GError, + ) -> *mut OstreeSign; + #[cfg(any(feature = "v2020_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] + pub fn ostree_sign_add_pk( + self_: *mut OstreeSign, + public_key: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] + pub fn ostree_sign_clear_keys( + self_: *mut OstreeSign, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] + pub fn ostree_sign_commit( + self_: *mut OstreeSign, + repo: *mut OstreeRepo, + commit_checksum: *const c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] + pub fn ostree_sign_commit_verify( + self_: *mut OstreeSign, + repo: *mut OstreeRepo, + commit_checksum: *const c_char, + out_success_message: *mut *mut c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] + pub fn ostree_sign_data( + self_: *mut OstreeSign, + data: *mut glib::GBytes, + signature: *mut *mut glib::GBytes, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] + pub fn ostree_sign_data_verify( + self_: *mut OstreeSign, + data: *mut glib::GBytes, + signatures: *mut glib::GVariant, + out_success_message: *mut *mut c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sign_dummy_add_pk( + self_: *mut OstreeSign, + key: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sign_dummy_data( + self_: *mut OstreeSign, + data: *mut glib::GBytes, + signature: *mut *mut glib::GBytes, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sign_dummy_data_verify( + self_: *mut OstreeSign, + data: *mut glib::GBytes, + signatures: *mut glib::GVariant, + success_message: *mut *mut c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sign_dummy_get_name(self_: *mut OstreeSign) -> *const c_char; + pub fn ostree_sign_dummy_metadata_format(self_: *mut OstreeSign) -> *const c_char; + pub fn ostree_sign_dummy_metadata_key(self_: *mut OstreeSign) -> *const c_char; + pub fn ostree_sign_dummy_set_pk( + self_: *mut OstreeSign, + key: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sign_dummy_set_sk( + self_: *mut OstreeSign, + key: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sign_ed25519_add_pk( + self_: *mut OstreeSign, + public_key: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sign_ed25519_clear_keys( + self_: *mut OstreeSign, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sign_ed25519_data( + self_: *mut OstreeSign, + data: *mut glib::GBytes, + signature: *mut *mut glib::GBytes, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sign_ed25519_data_verify( + self_: *mut OstreeSign, + data: *mut glib::GBytes, + signatures: *mut glib::GVariant, + out_success_message: *mut *mut c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sign_ed25519_get_name(self_: *mut OstreeSign) -> *const c_char; + pub fn ostree_sign_ed25519_load_pk( + self_: *mut OstreeSign, + options: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sign_ed25519_metadata_format(self_: *mut OstreeSign) -> *const c_char; + pub fn ostree_sign_ed25519_metadata_key(self_: *mut OstreeSign) -> *const c_char; + pub fn ostree_sign_ed25519_set_pk( + self_: *mut OstreeSign, + public_key: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_sign_ed25519_set_sk( + self_: *mut OstreeSign, + secret_key: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] + pub fn ostree_sign_get_name(self_: *mut OstreeSign) -> *const c_char; + #[cfg(any(feature = "v2020_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] + pub fn ostree_sign_load_pk( + self_: *mut OstreeSign, + options: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] + pub fn ostree_sign_metadata_format(self_: *mut OstreeSign) -> *const c_char; + #[cfg(any(feature = "v2020_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] + pub fn ostree_sign_metadata_key(self_: *mut OstreeSign) -> *const c_char; + #[cfg(any(feature = "v2020_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] + pub fn ostree_sign_set_pk( + self_: *mut OstreeSign, + public_key: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] + pub fn ostree_sign_set_sk( + self_: *mut OstreeSign, + secret_key: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2020_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_2")))] + pub fn ostree_sign_summary( + self_: *mut OstreeSign, + repo: *mut OstreeRepo, + keys: *mut glib::GVariant, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + + //========================================================================= + // Other functions + //========================================================================= + #[cfg(any(feature = "v2017_15", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_15")))] + pub fn ostree_break_hardlink( + dfd: c_int, + path: *const c_char, + skip_xattrs: gboolean, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2017_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_4")))] + pub fn ostree_check_version(required_year: c_uint, required_release: c_uint) -> gboolean; + #[cfg(any(feature = "v2016_8", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_8")))] + pub fn ostree_checksum_b64_from_bytes(csum: *const [c_uchar; 32]) -> *mut c_char; + pub fn ostree_checksum_b64_inplace_from_bytes(csum: *const [c_uchar; 32], buf: *mut c_char); + pub fn ostree_checksum_b64_inplace_to_bytes(checksum: *const [c_char; 32], buf: *mut u8); + #[cfg(any(feature = "v2016_8", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_8")))] + pub fn ostree_checksum_b64_to_bytes(checksum: *const c_char) -> *mut [c_uchar; 32]; + pub fn ostree_checksum_bytes_peek(bytes: *mut glib::GVariant) -> *const [c_uchar; 32]; + pub fn ostree_checksum_bytes_peek_validate( + bytes: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> *const [c_uchar; 32]; + pub fn ostree_checksum_file( + f: *mut gio::GFile, + objtype: OstreeObjectType, + out_csum: *mut *mut [*mut u8; 32], + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_checksum_file_async( + f: *mut gio::GFile, + objtype: OstreeObjectType, + io_priority: c_int, + cancellable: *mut gio::GCancellable, + callback: gio::GAsyncReadyCallback, + user_data: gpointer, + ); + pub fn ostree_checksum_file_async_finish( + f: *mut gio::GFile, + result: *mut gio::GAsyncResult, + out_csum: *mut *mut [*mut u8; 32], + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2017_13", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_13")))] + pub fn ostree_checksum_file_at( + dfd: c_int, + path: *const c_char, + stbuf: *mut stat, + objtype: OstreeObjectType, + flags: OstreeChecksumFlags, + out_checksum: *mut *mut c_char, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_checksum_file_from_input( + file_info: *mut gio::GFileInfo, + xattrs: *mut glib::GVariant, + in_: *mut gio::GInputStream, + objtype: OstreeObjectType, + out_csum: *mut *mut [*mut u8; 32], + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_checksum_from_bytes(csum: *const [c_uchar; 32]) -> *mut c_char; + pub fn ostree_checksum_from_bytes_v(csum_v: *mut glib::GVariant) -> *mut c_char; + pub fn ostree_checksum_inplace_from_bytes(csum: *const [c_uchar; 32], buf: *mut c_char); + pub fn ostree_checksum_inplace_to_bytes(checksum: *const c_char, buf: *mut u8); + pub fn ostree_checksum_to_bytes(checksum: *const c_char) -> *mut [c_uchar; 32]; + pub fn ostree_checksum_to_bytes_v(checksum: *const c_char) -> *mut glib::GVariant; + //pub fn ostree_cmd__private__() -> /*Ignored*/*const OstreeCmdPrivateVTable; + pub fn ostree_cmp_checksum_bytes(a: *const u8, b: *const u8) -> c_int; + #[cfg(any(feature = "v2018_2", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_2")))] + pub fn ostree_commit_get_content_checksum(commit_variant: *mut glib::GVariant) -> *mut c_char; + #[cfg(any(feature = "v2020_1", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2020_1")))] + pub fn ostree_commit_get_object_sizes( + commit_variant: *mut glib::GVariant, + out_sizes_entries: *mut *mut glib::GPtrArray, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_commit_get_parent(commit_variant: *mut glib::GVariant) -> *mut c_char; + #[cfg(any(feature = "v2016_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_3")))] + pub fn ostree_commit_get_timestamp(commit_variant: *mut glib::GVariant) -> u64; + #[cfg(any(feature = "v2021_1", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2021_1")))] + pub fn ostree_commit_metadata_for_bootable( + root: *mut gio::GFile, + dict: *mut glib::GVariantDict, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_content_file_parse( + compressed: gboolean, + content_path: *mut gio::GFile, + trusted: gboolean, + out_input: *mut *mut gio::GInputStream, + out_file_info: *mut *mut gio::GFileInfo, + out_xattrs: *mut *mut glib::GVariant, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_content_file_parse_at( + compressed: gboolean, + parent_dfd: c_int, + path: *const c_char, + trusted: gboolean, + out_input: *mut *mut gio::GInputStream, + out_file_info: *mut *mut gio::GFileInfo, + out_xattrs: *mut *mut glib::GVariant, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_content_stream_parse( + compressed: gboolean, + input: *mut gio::GInputStream, + input_length: u64, + trusted: gboolean, + out_input: *mut *mut gio::GInputStream, + out_file_info: *mut *mut gio::GFileInfo, + out_xattrs: *mut *mut glib::GVariant, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_create_directory_metadata( + dir_info: *mut gio::GFileInfo, + xattrs: *mut glib::GVariant, + ) -> *mut glib::GVariant; + pub fn ostree_diff_dirs( + flags: OstreeDiffFlags, + a: *mut gio::GFile, + b: *mut gio::GFile, + modified: *mut glib::GPtrArray, + removed: *mut glib::GPtrArray, + added: *mut glib::GPtrArray, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2017_4", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_4")))] + pub fn ostree_diff_dirs_with_options( + flags: OstreeDiffFlags, + a: *mut gio::GFile, + b: *mut gio::GFile, + modified: *mut glib::GPtrArray, + removed: *mut glib::GPtrArray, + added: *mut glib::GPtrArray, + options: *mut OstreeDiffDirsOptions, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_diff_print( + a: *mut gio::GFile, + b: *mut gio::GFile, + modified: *mut glib::GPtrArray, + removed: *mut glib::GPtrArray, + added: *mut glib::GPtrArray, + ); + #[cfg(any(feature = "v2017_10", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_10")))] + pub fn ostree_gpg_error_quark() -> glib::GQuark; + pub fn ostree_hash_object_name(a: gconstpointer) -> c_uint; + pub fn ostree_metadata_variant_type(objtype: OstreeObjectType) -> *const glib::GVariantType; + pub fn ostree_object_from_string( + str: *const c_char, + out_checksum: *mut *mut c_char, + out_objtype: *mut OstreeObjectType, + ); + pub fn ostree_object_name_deserialize( + variant: *mut glib::GVariant, + out_checksum: *mut *const c_char, + out_objtype: *mut OstreeObjectType, + ); + pub fn ostree_object_name_serialize( + checksum: *const c_char, + objtype: OstreeObjectType, + ) -> *mut glib::GVariant; + pub fn ostree_object_to_string( + checksum: *const c_char, + objtype: OstreeObjectType, + ) -> *mut c_char; + pub fn ostree_object_type_from_string(str: *const c_char) -> OstreeObjectType; + pub fn ostree_object_type_to_string(objtype: OstreeObjectType) -> *const c_char; + pub fn ostree_parse_refspec( + refspec: *const c_char, + out_remote: *mut *mut c_char, + out_ref: *mut *mut c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2016_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2016_6")))] + pub fn ostree_raw_file_to_archive_z2_stream( + input: *mut gio::GInputStream, + file_info: *mut gio::GFileInfo, + xattrs: *mut glib::GVariant, + out_input: *mut *mut gio::GInputStream, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2017_3", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_3")))] + pub fn ostree_raw_file_to_archive_z2_stream_with_options( + input: *mut gio::GInputStream, + file_info: *mut gio::GFileInfo, + xattrs: *mut glib::GVariant, + options: *mut glib::GVariant, + out_input: *mut *mut gio::GInputStream, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_raw_file_to_content_stream( + input: *mut gio::GInputStream, + file_info: *mut gio::GFileInfo, + xattrs: *mut glib::GVariant, + out_input: *mut *mut gio::GInputStream, + out_length: *mut u64, + cancellable: *mut gio::GCancellable, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_validate_checksum_string( + sha256: *const c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2018_6", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2018_6")))] + pub fn ostree_validate_collection_id( + collection_id: *const c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + #[cfg(any(feature = "v2017_8", feature = "dox"))] + #[cfg_attr(feature = "dox", doc(cfg(feature = "v2017_8")))] + pub fn ostree_validate_remote_name( + remote_name: *const c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_validate_rev(rev: *const c_char, error: *mut *mut glib::GError) -> gboolean; + pub fn ostree_validate_structureof_checksum_string( + checksum: *const c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_validate_structureof_commit( + commit: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_validate_structureof_csum_v( + checksum: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_validate_structureof_dirmeta( + dirmeta: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_validate_structureof_dirtree( + dirtree: *mut glib::GVariant, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_validate_structureof_file_mode( + mode: u32, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn ostree_validate_structureof_objtype( + objtype: c_uchar, + error: *mut *mut glib::GError, + ) -> gboolean; + +} diff --git a/rust-bindings/sys/src/manual.rs b/rust-bindings/sys/src/manual.rs new file mode 100644 index 0000000000..1319576ba4 --- /dev/null +++ b/rust-bindings/sys/src/manual.rs @@ -0,0 +1 @@ +pub use libc::stat; diff --git a/rust-bindings/sys/tests/abi.rs b/rust-bindings/sys/tests/abi.rs new file mode 100644 index 0000000000..19dd4c6244 --- /dev/null +++ b/rust-bindings/sys/tests/abi.rs @@ -0,0 +1,793 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +use ostree_sys::*; +use std::env; +use std::error::Error; +use std::ffi::OsString; +use std::mem::{align_of, size_of}; +use std::path::Path; +use std::process::Command; +use std::str; +use tempfile::Builder; + +static PACKAGES: &[&str] = &["ostree-1"]; + +#[derive(Clone, Debug)] +struct Compiler { + pub args: Vec<String>, +} + +impl Compiler { + pub fn new() -> Result<Self, Box<dyn Error>> { + let mut args = get_var("CC", "cc")?; + args.push("-Wno-deprecated-declarations".to_owned()); + // For _Generic + args.push("-std=c11".to_owned()); + // For %z support in printf when using MinGW. + args.push("-D__USE_MINGW_ANSI_STDIO".to_owned()); + args.extend(get_var("CFLAGS", "")?); + args.extend(get_var("CPPFLAGS", "")?); + args.extend(pkg_config_cflags(PACKAGES)?); + Ok(Self { args }) + } + + pub fn compile(&self, src: &Path, out: &Path) -> Result<(), Box<dyn Error>> { + let mut cmd = self.to_command(); + cmd.arg(src); + cmd.arg("-o"); + cmd.arg(out); + let status = cmd.spawn()?.wait()?; + if !status.success() { + return Err(format!("compilation command {:?} failed, {}", &cmd, status).into()); + } + Ok(()) + } + + fn to_command(&self) -> Command { + let mut cmd = Command::new(&self.args[0]); + cmd.args(&self.args[1..]); + cmd + } +} + +fn get_var(name: &str, default: &str) -> Result<Vec<String>, Box<dyn Error>> { + match env::var(name) { + Ok(value) => Ok(shell_words::split(&value)?), + Err(env::VarError::NotPresent) => Ok(shell_words::split(default)?), + Err(err) => Err(format!("{} {}", name, err).into()), + } +} + +fn pkg_config_cflags(packages: &[&str]) -> Result<Vec<String>, Box<dyn Error>> { + if packages.is_empty() { + return Ok(Vec::new()); + } + let pkg_config = env::var_os("PKG_CONFIG").unwrap_or_else(|| OsString::from("pkg-config")); + let mut cmd = Command::new(pkg_config); + cmd.arg("--cflags"); + cmd.args(packages); + let out = cmd.output()?; + if !out.status.success() { + return Err(format!("command {:?} returned {}", &cmd, out.status).into()); + } + let stdout = str::from_utf8(&out.stdout)?; + Ok(shell_words::split(stdout.trim())?) +} + +#[derive(Copy, Clone, Debug, Eq, PartialEq)] +struct Layout { + size: usize, + alignment: usize, +} + +#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)] +struct Results { + /// Number of successfully completed tests. + passed: usize, + /// Total number of failed tests (including those that failed to compile). + failed: usize, +} + +impl Results { + fn record_passed(&mut self) { + self.passed += 1; + } + fn record_failed(&mut self) { + self.failed += 1; + } + fn summary(&self) -> String { + format!("{} passed; {} failed", self.passed, self.failed) + } + fn expect_total_success(&self) { + if self.failed == 0 { + println!("OK: {}", self.summary()); + } else { + panic!("FAILED: {}", self.summary()); + }; + } +} + +#[test] +fn cross_validate_constants_with_c() { + let mut c_constants: Vec<(String, String)> = Vec::new(); + + for l in get_c_output("constant").unwrap().lines() { + let mut words = l.trim().split(';'); + let name = words.next().expect("Failed to parse name").to_owned(); + let value = words + .next() + .and_then(|s| s.parse().ok()) + .expect("Failed to parse value"); + c_constants.push((name, value)); + } + + let mut results = Results::default(); + + for ((rust_name, rust_value), (c_name, c_value)) in + RUST_CONSTANTS.iter().zip(c_constants.iter()) + { + if rust_name != c_name { + results.record_failed(); + eprintln!("Name mismatch:\nRust: {:?}\nC: {:?}", rust_name, c_name,); + continue; + } + + if rust_value != c_value { + results.record_failed(); + eprintln!( + "Constant value mismatch for {}\nRust: {:?}\nC: {:?}", + rust_name, rust_value, &c_value + ); + continue; + } + + results.record_passed(); + } + + results.expect_total_success(); +} + +#[test] +fn cross_validate_layout_with_c() { + let mut c_layouts = Vec::new(); + + for l in get_c_output("layout").unwrap().lines() { + let mut words = l.trim().split(';'); + let name = words.next().expect("Failed to parse name").to_owned(); + let size = words + .next() + .and_then(|s| s.parse().ok()) + .expect("Failed to parse size"); + let alignment = words + .next() + .and_then(|s| s.parse().ok()) + .expect("Failed to parse alignment"); + c_layouts.push((name, Layout { size, alignment })); + } + + let mut results = Results::default(); + + for ((rust_name, rust_layout), (c_name, c_layout)) in RUST_LAYOUTS.iter().zip(c_layouts.iter()) + { + if rust_name != c_name { + results.record_failed(); + eprintln!("Name mismatch:\nRust: {:?}\nC: {:?}", rust_name, c_name,); + continue; + } + + if rust_layout != c_layout { + results.record_failed(); + eprintln!( + "Layout mismatch for {}\nRust: {:?}\nC: {:?}", + rust_name, rust_layout, &c_layout + ); + continue; + } + + results.record_passed(); + } + + results.expect_total_success(); +} + +fn get_c_output(name: &str) -> Result<String, Box<dyn Error>> { + let tmpdir = Builder::new().prefix("abi").tempdir()?; + let exe = tmpdir.path().join(name); + let c_file = Path::new("tests").join(name).with_extension("c"); + + let cc = Compiler::new().expect("configured compiler"); + cc.compile(&c_file, &exe)?; + + let mut abi_cmd = Command::new(exe); + let output = abi_cmd.output()?; + if !output.status.success() { + return Err(format!("command {:?} failed, {:?}", &abi_cmd, &output).into()); + } + + Ok(String::from_utf8(output.stdout)?) +} + +const RUST_LAYOUTS: &[(&str, Layout)] = &[ + ( + "OstreeAsyncProgressClass", + Layout { + size: size_of::<OstreeAsyncProgressClass>(), + alignment: align_of::<OstreeAsyncProgressClass>(), + }, + ), + ( + "OstreeChecksumFlags", + Layout { + size: size_of::<OstreeChecksumFlags>(), + alignment: align_of::<OstreeChecksumFlags>(), + }, + ), + ( + "OstreeCollectionRef", + Layout { + size: size_of::<OstreeCollectionRef>(), + alignment: align_of::<OstreeCollectionRef>(), + }, + ), + ( + "OstreeCollectionRefv", + Layout { + size: size_of::<OstreeCollectionRefv>(), + alignment: align_of::<OstreeCollectionRefv>(), + }, + ), + ( + "OstreeCommitSizesEntry", + Layout { + size: size_of::<OstreeCommitSizesEntry>(), + alignment: align_of::<OstreeCommitSizesEntry>(), + }, + ), + ( + "OstreeContentWriterClass", + Layout { + size: size_of::<OstreeContentWriterClass>(), + alignment: align_of::<OstreeContentWriterClass>(), + }, + ), + ( + "OstreeDeploymentUnlockedState", + Layout { + size: size_of::<OstreeDeploymentUnlockedState>(), + alignment: align_of::<OstreeDeploymentUnlockedState>(), + }, + ), + ( + "OstreeDiffDirsOptions", + Layout { + size: size_of::<OstreeDiffDirsOptions>(), + alignment: align_of::<OstreeDiffDirsOptions>(), + }, + ), + ( + "OstreeDiffFlags", + Layout { + size: size_of::<OstreeDiffFlags>(), + alignment: align_of::<OstreeDiffFlags>(), + }, + ), + ( + "OstreeDiffItem", + Layout { + size: size_of::<OstreeDiffItem>(), + alignment: align_of::<OstreeDiffItem>(), + }, + ), + ( + "OstreeGpgError", + Layout { + size: size_of::<OstreeGpgError>(), + alignment: align_of::<OstreeGpgError>(), + }, + ), + ( + "OstreeGpgSignatureAttr", + Layout { + size: size_of::<OstreeGpgSignatureAttr>(), + alignment: align_of::<OstreeGpgSignatureAttr>(), + }, + ), + ( + "OstreeGpgSignatureFormatFlags", + Layout { + size: size_of::<OstreeGpgSignatureFormatFlags>(), + alignment: align_of::<OstreeGpgSignatureFormatFlags>(), + }, + ), + ( + "OstreeMutableTreeClass", + Layout { + size: size_of::<OstreeMutableTreeClass>(), + alignment: align_of::<OstreeMutableTreeClass>(), + }, + ), + ( + "OstreeMutableTreeIter", + Layout { + size: size_of::<OstreeMutableTreeIter>(), + alignment: align_of::<OstreeMutableTreeIter>(), + }, + ), + ( + "OstreeObjectType", + Layout { + size: size_of::<OstreeObjectType>(), + alignment: align_of::<OstreeObjectType>(), + }, + ), + ( + "OstreeRepoCheckoutAtOptions", + Layout { + size: size_of::<OstreeRepoCheckoutAtOptions>(), + alignment: align_of::<OstreeRepoCheckoutAtOptions>(), + }, + ), + ( + "OstreeRepoCheckoutFilterResult", + Layout { + size: size_of::<OstreeRepoCheckoutFilterResult>(), + alignment: align_of::<OstreeRepoCheckoutFilterResult>(), + }, + ), + ( + "OstreeRepoCheckoutMode", + Layout { + size: size_of::<OstreeRepoCheckoutMode>(), + alignment: align_of::<OstreeRepoCheckoutMode>(), + }, + ), + ( + "OstreeRepoCheckoutOverwriteMode", + Layout { + size: size_of::<OstreeRepoCheckoutOverwriteMode>(), + alignment: align_of::<OstreeRepoCheckoutOverwriteMode>(), + }, + ), + ( + "OstreeRepoCommitFilterResult", + Layout { + size: size_of::<OstreeRepoCommitFilterResult>(), + alignment: align_of::<OstreeRepoCommitFilterResult>(), + }, + ), + ( + "OstreeRepoCommitIterResult", + Layout { + size: size_of::<OstreeRepoCommitIterResult>(), + alignment: align_of::<OstreeRepoCommitIterResult>(), + }, + ), + ( + "OstreeRepoCommitModifierFlags", + Layout { + size: size_of::<OstreeRepoCommitModifierFlags>(), + alignment: align_of::<OstreeRepoCommitModifierFlags>(), + }, + ), + ( + "OstreeRepoCommitState", + Layout { + size: size_of::<OstreeRepoCommitState>(), + alignment: align_of::<OstreeRepoCommitState>(), + }, + ), + ( + "OstreeRepoCommitTraverseFlags", + Layout { + size: size_of::<OstreeRepoCommitTraverseFlags>(), + alignment: align_of::<OstreeRepoCommitTraverseFlags>(), + }, + ), + ( + "OstreeRepoCommitTraverseIter", + Layout { + size: size_of::<OstreeRepoCommitTraverseIter>(), + alignment: align_of::<OstreeRepoCommitTraverseIter>(), + }, + ), + ( + "OstreeRepoFileClass", + Layout { + size: size_of::<OstreeRepoFileClass>(), + alignment: align_of::<OstreeRepoFileClass>(), + }, + ), + ( + "OstreeRepoFinderAvahiClass", + Layout { + size: size_of::<OstreeRepoFinderAvahiClass>(), + alignment: align_of::<OstreeRepoFinderAvahiClass>(), + }, + ), + ( + "OstreeRepoFinderConfigClass", + Layout { + size: size_of::<OstreeRepoFinderConfigClass>(), + alignment: align_of::<OstreeRepoFinderConfigClass>(), + }, + ), + ( + "OstreeRepoFinderInterface", + Layout { + size: size_of::<OstreeRepoFinderInterface>(), + alignment: align_of::<OstreeRepoFinderInterface>(), + }, + ), + ( + "OstreeRepoFinderMountClass", + Layout { + size: size_of::<OstreeRepoFinderMountClass>(), + alignment: align_of::<OstreeRepoFinderMountClass>(), + }, + ), + ( + "OstreeRepoFinderOverrideClass", + Layout { + size: size_of::<OstreeRepoFinderOverrideClass>(), + alignment: align_of::<OstreeRepoFinderOverrideClass>(), + }, + ), + ( + "OstreeRepoFinderResult", + Layout { + size: size_of::<OstreeRepoFinderResult>(), + alignment: align_of::<OstreeRepoFinderResult>(), + }, + ), + ( + "OstreeRepoFinderResultv", + Layout { + size: size_of::<OstreeRepoFinderResultv>(), + alignment: align_of::<OstreeRepoFinderResultv>(), + }, + ), + ( + "OstreeRepoListObjectsFlags", + Layout { + size: size_of::<OstreeRepoListObjectsFlags>(), + alignment: align_of::<OstreeRepoListObjectsFlags>(), + }, + ), + ( + "OstreeRepoListRefsExtFlags", + Layout { + size: size_of::<OstreeRepoListRefsExtFlags>(), + alignment: align_of::<OstreeRepoListRefsExtFlags>(), + }, + ), + ( + "OstreeRepoLockType", + Layout { + size: size_of::<OstreeRepoLockType>(), + alignment: align_of::<OstreeRepoLockType>(), + }, + ), + ( + "OstreeRepoMode", + Layout { + size: size_of::<OstreeRepoMode>(), + alignment: align_of::<OstreeRepoMode>(), + }, + ), + ( + "OstreeRepoPruneFlags", + Layout { + size: size_of::<OstreeRepoPruneFlags>(), + alignment: align_of::<OstreeRepoPruneFlags>(), + }, + ), + ( + "OstreeRepoPruneOptions", + Layout { + size: size_of::<OstreeRepoPruneOptions>(), + alignment: align_of::<OstreeRepoPruneOptions>(), + }, + ), + ( + "OstreeRepoPullFlags", + Layout { + size: size_of::<OstreeRepoPullFlags>(), + alignment: align_of::<OstreeRepoPullFlags>(), + }, + ), + ( + "OstreeRepoRemoteChange", + Layout { + size: size_of::<OstreeRepoRemoteChange>(), + alignment: align_of::<OstreeRepoRemoteChange>(), + }, + ), + ( + "OstreeRepoResolveRevExtFlags", + Layout { + size: size_of::<OstreeRepoResolveRevExtFlags>(), + alignment: align_of::<OstreeRepoResolveRevExtFlags>(), + }, + ), + ( + "OstreeRepoTransactionStats", + Layout { + size: size_of::<OstreeRepoTransactionStats>(), + alignment: align_of::<OstreeRepoTransactionStats>(), + }, + ), + ( + "OstreeRepoVerifyFlags", + Layout { + size: size_of::<OstreeRepoVerifyFlags>(), + alignment: align_of::<OstreeRepoVerifyFlags>(), + }, + ), + ( + "OstreeSePolicyRestoreconFlags", + Layout { + size: size_of::<OstreeSePolicyRestoreconFlags>(), + alignment: align_of::<OstreeSePolicyRestoreconFlags>(), + }, + ), + ( + "OstreeSignInterface", + Layout { + size: size_of::<OstreeSignInterface>(), + alignment: align_of::<OstreeSignInterface>(), + }, + ), + ( + "OstreeStaticDeltaGenerateOpt", + Layout { + size: size_of::<OstreeStaticDeltaGenerateOpt>(), + alignment: align_of::<OstreeStaticDeltaGenerateOpt>(), + }, + ), + ( + "OstreeStaticDeltaIndexFlags", + Layout { + size: size_of::<OstreeStaticDeltaIndexFlags>(), + alignment: align_of::<OstreeStaticDeltaIndexFlags>(), + }, + ), + ( + "OstreeSysrootDeployTreeOpts", + Layout { + size: size_of::<OstreeSysrootDeployTreeOpts>(), + alignment: align_of::<OstreeSysrootDeployTreeOpts>(), + }, + ), + ( + "OstreeSysrootSimpleWriteDeploymentFlags", + Layout { + size: size_of::<OstreeSysrootSimpleWriteDeploymentFlags>(), + alignment: align_of::<OstreeSysrootSimpleWriteDeploymentFlags>(), + }, + ), + ( + "OstreeSysrootUpgraderFlags", + Layout { + size: size_of::<OstreeSysrootUpgraderFlags>(), + alignment: align_of::<OstreeSysrootUpgraderFlags>(), + }, + ), + ( + "OstreeSysrootUpgraderPullFlags", + Layout { + size: size_of::<OstreeSysrootUpgraderPullFlags>(), + alignment: align_of::<OstreeSysrootUpgraderPullFlags>(), + }, + ), + ( + "OstreeSysrootWriteDeploymentsOpts", + Layout { + size: size_of::<OstreeSysrootWriteDeploymentsOpts>(), + alignment: align_of::<OstreeSysrootWriteDeploymentsOpts>(), + }, + ), +]; + +const RUST_CONSTANTS: &[(&str, &str)] = &[ + ("(guint) OSTREE_CHECKSUM_FLAGS_CANONICAL_PERMISSIONS", "2"), + ("(guint) OSTREE_CHECKSUM_FLAGS_IGNORE_XATTRS", "1"), + ("(guint) OSTREE_CHECKSUM_FLAGS_NONE", "0"), + ("OSTREE_COMMIT_GVARIANT_STRING", "(a{sv}aya(say)sstayay)"), + ("OSTREE_COMMIT_META_KEY_ARCHITECTURE", "ostree.architecture"), + ( + "OSTREE_COMMIT_META_KEY_COLLECTION_BINDING", + "ostree.collection-binding", + ), + ("OSTREE_COMMIT_META_KEY_ENDOFLIFE", "ostree.endoflife"), + ( + "OSTREE_COMMIT_META_KEY_ENDOFLIFE_REBASE", + "ostree.endoflife-rebase", + ), + ("OSTREE_COMMIT_META_KEY_REF_BINDING", "ostree.ref-binding"), + ("OSTREE_COMMIT_META_KEY_SOURCE_TITLE", "ostree.source-title"), + ("OSTREE_COMMIT_META_KEY_VERSION", "version"), + ("(gint) OSTREE_DEPLOYMENT_UNLOCKED_DEVELOPMENT", "1"), + ("(gint) OSTREE_DEPLOYMENT_UNLOCKED_HOTFIX", "2"), + ("(gint) OSTREE_DEPLOYMENT_UNLOCKED_NONE", "0"), + ("(gint) OSTREE_DEPLOYMENT_UNLOCKED_TRANSIENT", "3"), + ("(guint) OSTREE_DIFF_FLAGS_IGNORE_XATTRS", "1"), + ("(guint) OSTREE_DIFF_FLAGS_NONE", "0"), + ("OSTREE_DIRMETA_GVARIANT_STRING", "(uuua(ayay))"), + ("OSTREE_FILEMETA_GVARIANT_STRING", "(uuua(ayay))"), + ("(gint) OSTREE_GPG_ERROR_EXPIRED_KEY", "4"), + ("(gint) OSTREE_GPG_ERROR_EXPIRED_SIGNATURE", "3"), + ("(gint) OSTREE_GPG_ERROR_INVALID_SIGNATURE", "1"), + ("(gint) OSTREE_GPG_ERROR_MISSING_KEY", "2"), + ("(gint) OSTREE_GPG_ERROR_NO_SIGNATURE", "0"), + ("(gint) OSTREE_GPG_ERROR_REVOKED_KEY", "5"), + ("OSTREE_GPG_KEY_GVARIANT_STRING", "(aa{sv}aa{sv}a{sv})"), + ("(gint) OSTREE_GPG_SIGNATURE_ATTR_EXP_TIMESTAMP", "7"), + ("(gint) OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT", "5"), + ("(gint) OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT_PRIMARY", "12"), + ("(gint) OSTREE_GPG_SIGNATURE_ATTR_HASH_ALGO_NAME", "9"), + ("(gint) OSTREE_GPG_SIGNATURE_ATTR_KEY_EXPIRED", "2"), + ("(gint) OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP", "13"), + ( + "(gint) OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP_PRIMARY", + "14", + ), + ("(gint) OSTREE_GPG_SIGNATURE_ATTR_KEY_MISSING", "4"), + ("(gint) OSTREE_GPG_SIGNATURE_ATTR_KEY_REVOKED", "3"), + ("(gint) OSTREE_GPG_SIGNATURE_ATTR_PUBKEY_ALGO_NAME", "8"), + ("(gint) OSTREE_GPG_SIGNATURE_ATTR_SIG_EXPIRED", "1"), + ("(gint) OSTREE_GPG_SIGNATURE_ATTR_TIMESTAMP", "6"), + ("(gint) OSTREE_GPG_SIGNATURE_ATTR_USER_EMAIL", "11"), + ("(gint) OSTREE_GPG_SIGNATURE_ATTR_USER_NAME", "10"), + ("(gint) OSTREE_GPG_SIGNATURE_ATTR_VALID", "0"), + ("(guint) OSTREE_GPG_SIGNATURE_FORMAT_DEFAULT", "0"), + ("OSTREE_MAX_METADATA_SIZE", "10485760"), + ("OSTREE_MAX_METADATA_WARN_SIZE", "7340032"), + ("OSTREE_METADATA_KEY_BOOTABLE", "ostree.bootable"), + ("OSTREE_METADATA_KEY_LINUX", "ostree.linux"), + ( + "OSTREE_META_KEY_DEPLOY_COLLECTION_ID", + "ostree.deploy-collection-id", + ), + ("(gint) OSTREE_OBJECT_TYPE_COMMIT", "4"), + ("(gint) OSTREE_OBJECT_TYPE_COMMIT_META", "6"), + ("(gint) OSTREE_OBJECT_TYPE_DIR_META", "3"), + ("(gint) OSTREE_OBJECT_TYPE_DIR_TREE", "2"), + ("(gint) OSTREE_OBJECT_TYPE_FILE", "1"), + ("(gint) OSTREE_OBJECT_TYPE_FILE_XATTRS", "8"), + ("(gint) OSTREE_OBJECT_TYPE_FILE_XATTRS_LINK", "9"), + ("(gint) OSTREE_OBJECT_TYPE_PAYLOAD_LINK", "7"), + ("(gint) OSTREE_OBJECT_TYPE_TOMBSTONE_COMMIT", "5"), + ("OSTREE_ORIGIN_TRANSIENT_GROUP", "libostree-transient"), + ("OSTREE_PATH_BOOTED", "/run/ostree-booted"), + ("(gint) OSTREE_REPO_CHECKOUT_FILTER_ALLOW", "0"), + ("(gint) OSTREE_REPO_CHECKOUT_FILTER_SKIP", "1"), + ("(gint) OSTREE_REPO_CHECKOUT_MODE_NONE", "0"), + ("(gint) OSTREE_REPO_CHECKOUT_MODE_USER", "1"), + ("(gint) OSTREE_REPO_CHECKOUT_OVERWRITE_ADD_FILES", "2"), + ("(gint) OSTREE_REPO_CHECKOUT_OVERWRITE_NONE", "0"), + ("(gint) OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_FILES", "1"), + ("(gint) OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_IDENTICAL", "3"), + ("(gint) OSTREE_REPO_COMMIT_FILTER_ALLOW", "0"), + ("(gint) OSTREE_REPO_COMMIT_FILTER_SKIP", "1"), + ("(gint) OSTREE_REPO_COMMIT_ITER_RESULT_DIR", "3"), + ("(gint) OSTREE_REPO_COMMIT_ITER_RESULT_END", "1"), + ("(gint) OSTREE_REPO_COMMIT_ITER_RESULT_ERROR", "0"), + ("(gint) OSTREE_REPO_COMMIT_ITER_RESULT_FILE", "2"), + ( + "(guint) OSTREE_REPO_COMMIT_MODIFIER_FLAGS_CANONICAL_PERMISSIONS", + "4", + ), + ("(guint) OSTREE_REPO_COMMIT_MODIFIER_FLAGS_CONSUME", "16"), + ( + "(guint) OSTREE_REPO_COMMIT_MODIFIER_FLAGS_DEVINO_CANONICAL", + "32", + ), + ( + "(guint) OSTREE_REPO_COMMIT_MODIFIER_FLAGS_ERROR_ON_UNLABELED", + "8", + ), + ( + "(guint) OSTREE_REPO_COMMIT_MODIFIER_FLAGS_GENERATE_SIZES", + "2", + ), + ("(guint) OSTREE_REPO_COMMIT_MODIFIER_FLAGS_NONE", "0"), + ("(guint) OSTREE_REPO_COMMIT_MODIFIER_FLAGS_SKIP_XATTRS", "1"), + ("(guint) OSTREE_REPO_COMMIT_STATE_FSCK_PARTIAL", "2"), + ("(guint) OSTREE_REPO_COMMIT_STATE_NORMAL", "0"), + ("(guint) OSTREE_REPO_COMMIT_STATE_PARTIAL", "1"), + ("(guint) OSTREE_REPO_COMMIT_TRAVERSE_FLAG_COMMIT_ONLY", "2"), + ("(guint) OSTREE_REPO_COMMIT_TRAVERSE_FLAG_NONE", "1"), + ("(guint) OSTREE_REPO_LIST_OBJECTS_ALL", "4"), + ("(guint) OSTREE_REPO_LIST_OBJECTS_LOOSE", "1"), + ("(guint) OSTREE_REPO_LIST_OBJECTS_NO_PARENTS", "8"), + ("(guint) OSTREE_REPO_LIST_OBJECTS_PACKED", "2"), + ("(guint) OSTREE_REPO_LIST_REFS_EXT_ALIASES", "1"), + ("(guint) OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_MIRRORS", "4"), + ("(guint) OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_REMOTES", "2"), + ("(guint) OSTREE_REPO_LIST_REFS_EXT_NONE", "0"), + ("(gint) OSTREE_REPO_LOCK_EXCLUSIVE", "1"), + ("(gint) OSTREE_REPO_LOCK_SHARED", "0"), + ("OSTREE_REPO_METADATA_REF", "ostree-metadata"), + ("(gint) OSTREE_REPO_MODE_ARCHIVE", "1"), + ("(gint) OSTREE_REPO_MODE_ARCHIVE_Z2", "1"), + ("(gint) OSTREE_REPO_MODE_BARE", "0"), + ("(gint) OSTREE_REPO_MODE_BARE_SPLIT_XATTRS", "4"), + ("(gint) OSTREE_REPO_MODE_BARE_USER", "2"), + ("(gint) OSTREE_REPO_MODE_BARE_USER_ONLY", "3"), + ("(guint) OSTREE_REPO_PRUNE_FLAGS_COMMIT_ONLY", "4"), + ("(guint) OSTREE_REPO_PRUNE_FLAGS_NONE", "0"), + ("(guint) OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE", "1"), + ("(guint) OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY", "2"), + ("(guint) OSTREE_REPO_PULL_FLAGS_BAREUSERONLY_FILES", "8"), + ("(guint) OSTREE_REPO_PULL_FLAGS_COMMIT_ONLY", "2"), + ("(guint) OSTREE_REPO_PULL_FLAGS_MIRROR", "1"), + ("(guint) OSTREE_REPO_PULL_FLAGS_NONE", "0"), + ("(guint) OSTREE_REPO_PULL_FLAGS_TRUSTED_HTTP", "16"), + ("(guint) OSTREE_REPO_PULL_FLAGS_UNTRUSTED", "4"), + ("(gint) OSTREE_REPO_REMOTE_CHANGE_ADD", "0"), + ("(gint) OSTREE_REPO_REMOTE_CHANGE_ADD_IF_NOT_EXISTS", "1"), + ("(gint) OSTREE_REPO_REMOTE_CHANGE_DELETE", "2"), + ("(gint) OSTREE_REPO_REMOTE_CHANGE_DELETE_IF_EXISTS", "3"), + ("(gint) OSTREE_REPO_REMOTE_CHANGE_REPLACE", "4"), + ("(guint) OSTREE_REPO_RESOLVE_REV_EXT_LOCAL_ONLY", "1"), + ("(guint) OSTREE_REPO_RESOLVE_REV_EXT_NONE", "0"), + ("(guint) OSTREE_REPO_VERIFY_FLAGS_NONE", "0"), + ("(guint) OSTREE_REPO_VERIFY_FLAGS_NO_GPG", "1"), + ("(guint) OSTREE_REPO_VERIFY_FLAGS_NO_SIGNAPI", "2"), + ( + "(guint) OSTREE_SEPOLICY_RESTORECON_FLAGS_ALLOW_NOLABEL", + "1", + ), + ( + "(guint) OSTREE_SEPOLICY_RESTORECON_FLAGS_KEEP_EXISTING", + "2", + ), + ("(guint) OSTREE_SEPOLICY_RESTORECON_FLAGS_NONE", "0"), + ("OSTREE_SHA256_DIGEST_LEN", "32"), + ("OSTREE_SHA256_STRING_LEN", "64"), + ("OSTREE_SIGN_NAME_ED25519", "ed25519"), + ("(gint) OSTREE_STATIC_DELTA_GENERATE_OPT_LOWLATENCY", "0"), + ("(gint) OSTREE_STATIC_DELTA_GENERATE_OPT_MAJOR", "1"), + ("(gint) OSTREE_STATIC_DELTA_INDEX_FLAGS_NONE", "0"), + ("OSTREE_SUMMARY_GVARIANT_STRING", "(a(s(taya{sv}))a{sv})"), + ("OSTREE_SUMMARY_SIG_GVARIANT_STRING", "a{sv}"), + ( + "(guint) OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NONE", + "0", + ), + ( + "(guint) OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NOT_DEFAULT", + "2", + ), + ( + "(guint) OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NO_CLEAN", + "4", + ), + ( + "(guint) OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN", + "1", + ), + ( + "(guint) OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_PENDING", + "8", + ), + ( + "(guint) OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_ROLLBACK", + "16", + ), + ( + "(guint) OSTREE_SYSROOT_UPGRADER_FLAGS_IGNORE_UNCONFIGURED", + "2", + ), + ("(guint) OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE", "4"), + ( + "(guint) OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_ALLOW_OLDER", + "1", + ), + ("(guint) OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_NONE", "0"), + ("(guint) OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_SYNTHETIC", "2"), + ("OSTREE_TIMESTAMP", "0"), + ("OSTREE_TREE_GVARIANT_STRING", "(a(say)a(sayay))"), +]; diff --git a/rust-bindings/sys/tests/constant.c b/rust-bindings/sys/tests/constant.c new file mode 100644 index 0000000000..d65f46665e --- /dev/null +++ b/rust-bindings/sys/tests/constant.c @@ -0,0 +1,177 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +#include "manual.h" +#include <stdio.h> + +#define PRINT_CONSTANT(CONSTANT_NAME) \ + printf("%s;", #CONSTANT_NAME); \ + printf(_Generic((CONSTANT_NAME), \ + char *: "%s", \ + const char *: "%s", \ + char: "%c", \ + signed char: "%hhd", \ + unsigned char: "%hhu", \ + short int: "%hd", \ + unsigned short int: "%hu", \ + int: "%d", \ + unsigned int: "%u", \ + long: "%ld", \ + unsigned long: "%lu", \ + long long: "%lld", \ + unsigned long long: "%llu", \ + float: "%f", \ + double: "%f", \ + long double: "%ld"), \ + CONSTANT_NAME); \ + printf("\n"); + +int main() { + PRINT_CONSTANT((guint) OSTREE_CHECKSUM_FLAGS_CANONICAL_PERMISSIONS); + PRINT_CONSTANT((guint) OSTREE_CHECKSUM_FLAGS_IGNORE_XATTRS); + PRINT_CONSTANT((guint) OSTREE_CHECKSUM_FLAGS_NONE); + PRINT_CONSTANT(OSTREE_COMMIT_GVARIANT_STRING); + PRINT_CONSTANT(OSTREE_COMMIT_META_KEY_ARCHITECTURE); + PRINT_CONSTANT(OSTREE_COMMIT_META_KEY_COLLECTION_BINDING); + PRINT_CONSTANT(OSTREE_COMMIT_META_KEY_ENDOFLIFE); + PRINT_CONSTANT(OSTREE_COMMIT_META_KEY_ENDOFLIFE_REBASE); + PRINT_CONSTANT(OSTREE_COMMIT_META_KEY_REF_BINDING); + PRINT_CONSTANT(OSTREE_COMMIT_META_KEY_SOURCE_TITLE); + PRINT_CONSTANT(OSTREE_COMMIT_META_KEY_VERSION); + PRINT_CONSTANT((gint) OSTREE_DEPLOYMENT_UNLOCKED_DEVELOPMENT); + PRINT_CONSTANT((gint) OSTREE_DEPLOYMENT_UNLOCKED_HOTFIX); + PRINT_CONSTANT((gint) OSTREE_DEPLOYMENT_UNLOCKED_NONE); + PRINT_CONSTANT((gint) OSTREE_DEPLOYMENT_UNLOCKED_TRANSIENT); + PRINT_CONSTANT((guint) OSTREE_DIFF_FLAGS_IGNORE_XATTRS); + PRINT_CONSTANT((guint) OSTREE_DIFF_FLAGS_NONE); + PRINT_CONSTANT(OSTREE_DIRMETA_GVARIANT_STRING); + PRINT_CONSTANT(OSTREE_FILEMETA_GVARIANT_STRING); + PRINT_CONSTANT((gint) OSTREE_GPG_ERROR_EXPIRED_KEY); + PRINT_CONSTANT((gint) OSTREE_GPG_ERROR_EXPIRED_SIGNATURE); + PRINT_CONSTANT((gint) OSTREE_GPG_ERROR_INVALID_SIGNATURE); + PRINT_CONSTANT((gint) OSTREE_GPG_ERROR_MISSING_KEY); + PRINT_CONSTANT((gint) OSTREE_GPG_ERROR_NO_SIGNATURE); + PRINT_CONSTANT((gint) OSTREE_GPG_ERROR_REVOKED_KEY); + PRINT_CONSTANT(OSTREE_GPG_KEY_GVARIANT_STRING); + PRINT_CONSTANT((gint) OSTREE_GPG_SIGNATURE_ATTR_EXP_TIMESTAMP); + PRINT_CONSTANT((gint) OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT); + PRINT_CONSTANT((gint) OSTREE_GPG_SIGNATURE_ATTR_FINGERPRINT_PRIMARY); + PRINT_CONSTANT((gint) OSTREE_GPG_SIGNATURE_ATTR_HASH_ALGO_NAME); + PRINT_CONSTANT((gint) OSTREE_GPG_SIGNATURE_ATTR_KEY_EXPIRED); + PRINT_CONSTANT((gint) OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP); + PRINT_CONSTANT((gint) OSTREE_GPG_SIGNATURE_ATTR_KEY_EXP_TIMESTAMP_PRIMARY); + PRINT_CONSTANT((gint) OSTREE_GPG_SIGNATURE_ATTR_KEY_MISSING); + PRINT_CONSTANT((gint) OSTREE_GPG_SIGNATURE_ATTR_KEY_REVOKED); + PRINT_CONSTANT((gint) OSTREE_GPG_SIGNATURE_ATTR_PUBKEY_ALGO_NAME); + PRINT_CONSTANT((gint) OSTREE_GPG_SIGNATURE_ATTR_SIG_EXPIRED); + PRINT_CONSTANT((gint) OSTREE_GPG_SIGNATURE_ATTR_TIMESTAMP); + PRINT_CONSTANT((gint) OSTREE_GPG_SIGNATURE_ATTR_USER_EMAIL); + PRINT_CONSTANT((gint) OSTREE_GPG_SIGNATURE_ATTR_USER_NAME); + PRINT_CONSTANT((gint) OSTREE_GPG_SIGNATURE_ATTR_VALID); + PRINT_CONSTANT((guint) OSTREE_GPG_SIGNATURE_FORMAT_DEFAULT); + PRINT_CONSTANT(OSTREE_MAX_METADATA_SIZE); + PRINT_CONSTANT(OSTREE_MAX_METADATA_WARN_SIZE); + PRINT_CONSTANT(OSTREE_METADATA_KEY_BOOTABLE); + PRINT_CONSTANT(OSTREE_METADATA_KEY_LINUX); + PRINT_CONSTANT(OSTREE_META_KEY_DEPLOY_COLLECTION_ID); + PRINT_CONSTANT((gint) OSTREE_OBJECT_TYPE_COMMIT); + PRINT_CONSTANT((gint) OSTREE_OBJECT_TYPE_COMMIT_META); + PRINT_CONSTANT((gint) OSTREE_OBJECT_TYPE_DIR_META); + PRINT_CONSTANT((gint) OSTREE_OBJECT_TYPE_DIR_TREE); + PRINT_CONSTANT((gint) OSTREE_OBJECT_TYPE_FILE); + PRINT_CONSTANT((gint) OSTREE_OBJECT_TYPE_FILE_XATTRS); + PRINT_CONSTANT((gint) OSTREE_OBJECT_TYPE_FILE_XATTRS_LINK); + PRINT_CONSTANT((gint) OSTREE_OBJECT_TYPE_PAYLOAD_LINK); + PRINT_CONSTANT((gint) OSTREE_OBJECT_TYPE_TOMBSTONE_COMMIT); + PRINT_CONSTANT(OSTREE_ORIGIN_TRANSIENT_GROUP); + PRINT_CONSTANT(OSTREE_PATH_BOOTED); + PRINT_CONSTANT((gint) OSTREE_REPO_CHECKOUT_FILTER_ALLOW); + PRINT_CONSTANT((gint) OSTREE_REPO_CHECKOUT_FILTER_SKIP); + PRINT_CONSTANT((gint) OSTREE_REPO_CHECKOUT_MODE_NONE); + PRINT_CONSTANT((gint) OSTREE_REPO_CHECKOUT_MODE_USER); + PRINT_CONSTANT((gint) OSTREE_REPO_CHECKOUT_OVERWRITE_ADD_FILES); + PRINT_CONSTANT((gint) OSTREE_REPO_CHECKOUT_OVERWRITE_NONE); + PRINT_CONSTANT((gint) OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_FILES); + PRINT_CONSTANT((gint) OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_IDENTICAL); + PRINT_CONSTANT((gint) OSTREE_REPO_COMMIT_FILTER_ALLOW); + PRINT_CONSTANT((gint) OSTREE_REPO_COMMIT_FILTER_SKIP); + PRINT_CONSTANT((gint) OSTREE_REPO_COMMIT_ITER_RESULT_DIR); + PRINT_CONSTANT((gint) OSTREE_REPO_COMMIT_ITER_RESULT_END); + PRINT_CONSTANT((gint) OSTREE_REPO_COMMIT_ITER_RESULT_ERROR); + PRINT_CONSTANT((gint) OSTREE_REPO_COMMIT_ITER_RESULT_FILE); + PRINT_CONSTANT((guint) OSTREE_REPO_COMMIT_MODIFIER_FLAGS_CANONICAL_PERMISSIONS); + PRINT_CONSTANT((guint) OSTREE_REPO_COMMIT_MODIFIER_FLAGS_CONSUME); + PRINT_CONSTANT((guint) OSTREE_REPO_COMMIT_MODIFIER_FLAGS_DEVINO_CANONICAL); + PRINT_CONSTANT((guint) OSTREE_REPO_COMMIT_MODIFIER_FLAGS_ERROR_ON_UNLABELED); + PRINT_CONSTANT((guint) OSTREE_REPO_COMMIT_MODIFIER_FLAGS_GENERATE_SIZES); + PRINT_CONSTANT((guint) OSTREE_REPO_COMMIT_MODIFIER_FLAGS_NONE); + PRINT_CONSTANT((guint) OSTREE_REPO_COMMIT_MODIFIER_FLAGS_SKIP_XATTRS); + PRINT_CONSTANT((guint) OSTREE_REPO_COMMIT_STATE_FSCK_PARTIAL); + PRINT_CONSTANT((guint) OSTREE_REPO_COMMIT_STATE_NORMAL); + PRINT_CONSTANT((guint) OSTREE_REPO_COMMIT_STATE_PARTIAL); + PRINT_CONSTANT((guint) OSTREE_REPO_COMMIT_TRAVERSE_FLAG_COMMIT_ONLY); + PRINT_CONSTANT((guint) OSTREE_REPO_COMMIT_TRAVERSE_FLAG_NONE); + PRINT_CONSTANT((guint) OSTREE_REPO_LIST_OBJECTS_ALL); + PRINT_CONSTANT((guint) OSTREE_REPO_LIST_OBJECTS_LOOSE); + PRINT_CONSTANT((guint) OSTREE_REPO_LIST_OBJECTS_NO_PARENTS); + PRINT_CONSTANT((guint) OSTREE_REPO_LIST_OBJECTS_PACKED); + PRINT_CONSTANT((guint) OSTREE_REPO_LIST_REFS_EXT_ALIASES); + PRINT_CONSTANT((guint) OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_MIRRORS); + PRINT_CONSTANT((guint) OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_REMOTES); + PRINT_CONSTANT((guint) OSTREE_REPO_LIST_REFS_EXT_NONE); + PRINT_CONSTANT((gint) OSTREE_REPO_LOCK_EXCLUSIVE); + PRINT_CONSTANT((gint) OSTREE_REPO_LOCK_SHARED); + PRINT_CONSTANT(OSTREE_REPO_METADATA_REF); + PRINT_CONSTANT((gint) OSTREE_REPO_MODE_ARCHIVE); + PRINT_CONSTANT((gint) OSTREE_REPO_MODE_ARCHIVE_Z2); + PRINT_CONSTANT((gint) OSTREE_REPO_MODE_BARE); + PRINT_CONSTANT((gint) OSTREE_REPO_MODE_BARE_SPLIT_XATTRS); + PRINT_CONSTANT((gint) OSTREE_REPO_MODE_BARE_USER); + PRINT_CONSTANT((gint) OSTREE_REPO_MODE_BARE_USER_ONLY); + PRINT_CONSTANT((guint) OSTREE_REPO_PRUNE_FLAGS_COMMIT_ONLY); + PRINT_CONSTANT((guint) OSTREE_REPO_PRUNE_FLAGS_NONE); + PRINT_CONSTANT((guint) OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE); + PRINT_CONSTANT((guint) OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY); + PRINT_CONSTANT((guint) OSTREE_REPO_PULL_FLAGS_BAREUSERONLY_FILES); + PRINT_CONSTANT((guint) OSTREE_REPO_PULL_FLAGS_COMMIT_ONLY); + PRINT_CONSTANT((guint) OSTREE_REPO_PULL_FLAGS_MIRROR); + PRINT_CONSTANT((guint) OSTREE_REPO_PULL_FLAGS_NONE); + PRINT_CONSTANT((guint) OSTREE_REPO_PULL_FLAGS_TRUSTED_HTTP); + PRINT_CONSTANT((guint) OSTREE_REPO_PULL_FLAGS_UNTRUSTED); + PRINT_CONSTANT((gint) OSTREE_REPO_REMOTE_CHANGE_ADD); + PRINT_CONSTANT((gint) OSTREE_REPO_REMOTE_CHANGE_ADD_IF_NOT_EXISTS); + PRINT_CONSTANT((gint) OSTREE_REPO_REMOTE_CHANGE_DELETE); + PRINT_CONSTANT((gint) OSTREE_REPO_REMOTE_CHANGE_DELETE_IF_EXISTS); + PRINT_CONSTANT((gint) OSTREE_REPO_REMOTE_CHANGE_REPLACE); + PRINT_CONSTANT((guint) OSTREE_REPO_RESOLVE_REV_EXT_LOCAL_ONLY); + PRINT_CONSTANT((guint) OSTREE_REPO_RESOLVE_REV_EXT_NONE); + PRINT_CONSTANT((guint) OSTREE_REPO_VERIFY_FLAGS_NONE); + PRINT_CONSTANT((guint) OSTREE_REPO_VERIFY_FLAGS_NO_GPG); + PRINT_CONSTANT((guint) OSTREE_REPO_VERIFY_FLAGS_NO_SIGNAPI); + PRINT_CONSTANT((guint) OSTREE_SEPOLICY_RESTORECON_FLAGS_ALLOW_NOLABEL); + PRINT_CONSTANT((guint) OSTREE_SEPOLICY_RESTORECON_FLAGS_KEEP_EXISTING); + PRINT_CONSTANT((guint) OSTREE_SEPOLICY_RESTORECON_FLAGS_NONE); + PRINT_CONSTANT(OSTREE_SHA256_DIGEST_LEN); + PRINT_CONSTANT(OSTREE_SHA256_STRING_LEN); + PRINT_CONSTANT(OSTREE_SIGN_NAME_ED25519); + PRINT_CONSTANT((gint) OSTREE_STATIC_DELTA_GENERATE_OPT_LOWLATENCY); + PRINT_CONSTANT((gint) OSTREE_STATIC_DELTA_GENERATE_OPT_MAJOR); + PRINT_CONSTANT((gint) OSTREE_STATIC_DELTA_INDEX_FLAGS_NONE); + PRINT_CONSTANT(OSTREE_SUMMARY_GVARIANT_STRING); + PRINT_CONSTANT(OSTREE_SUMMARY_SIG_GVARIANT_STRING); + PRINT_CONSTANT((guint) OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NONE); + PRINT_CONSTANT((guint) OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NOT_DEFAULT); + PRINT_CONSTANT((guint) OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NO_CLEAN); + PRINT_CONSTANT((guint) OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN); + PRINT_CONSTANT((guint) OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_PENDING); + PRINT_CONSTANT((guint) OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN_ROLLBACK); + PRINT_CONSTANT((guint) OSTREE_SYSROOT_UPGRADER_FLAGS_IGNORE_UNCONFIGURED); + PRINT_CONSTANT((guint) OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE); + PRINT_CONSTANT((guint) OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_ALLOW_OLDER); + PRINT_CONSTANT((guint) OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_NONE); + PRINT_CONSTANT((guint) OSTREE_SYSROOT_UPGRADER_PULL_FLAGS_SYNTHETIC); + PRINT_CONSTANT(OSTREE_TIMESTAMP); + PRINT_CONSTANT(OSTREE_TREE_GVARIANT_STRING); + return 0; +} diff --git a/rust-bindings/sys/tests/layout.c b/rust-bindings/sys/tests/layout.c new file mode 100644 index 0000000000..0def4cc77e --- /dev/null +++ b/rust-bindings/sys/tests/layout.c @@ -0,0 +1,65 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files +// DO NOT EDIT + +#include "manual.h" +#include <stdalign.h> +#include <stdio.h> + +int main() { + printf("%s;%zu;%zu\n", "OstreeAsyncProgressClass", sizeof(OstreeAsyncProgressClass), alignof(OstreeAsyncProgressClass)); + printf("%s;%zu;%zu\n", "OstreeChecksumFlags", sizeof(OstreeChecksumFlags), alignof(OstreeChecksumFlags)); + printf("%s;%zu;%zu\n", "OstreeCollectionRef", sizeof(OstreeCollectionRef), alignof(OstreeCollectionRef)); + printf("%s;%zu;%zu\n", "OstreeCollectionRefv", sizeof(OstreeCollectionRefv), alignof(OstreeCollectionRefv)); + printf("%s;%zu;%zu\n", "OstreeCommitSizesEntry", sizeof(OstreeCommitSizesEntry), alignof(OstreeCommitSizesEntry)); + printf("%s;%zu;%zu\n", "OstreeContentWriterClass", sizeof(OstreeContentWriterClass), alignof(OstreeContentWriterClass)); + printf("%s;%zu;%zu\n", "OstreeDeploymentUnlockedState", sizeof(OstreeDeploymentUnlockedState), alignof(OstreeDeploymentUnlockedState)); + printf("%s;%zu;%zu\n", "OstreeDiffDirsOptions", sizeof(OstreeDiffDirsOptions), alignof(OstreeDiffDirsOptions)); + printf("%s;%zu;%zu\n", "OstreeDiffFlags", sizeof(OstreeDiffFlags), alignof(OstreeDiffFlags)); + printf("%s;%zu;%zu\n", "OstreeDiffItem", sizeof(OstreeDiffItem), alignof(OstreeDiffItem)); + printf("%s;%zu;%zu\n", "OstreeGpgError", sizeof(OstreeGpgError), alignof(OstreeGpgError)); + printf("%s;%zu;%zu\n", "OstreeGpgSignatureAttr", sizeof(OstreeGpgSignatureAttr), alignof(OstreeGpgSignatureAttr)); + printf("%s;%zu;%zu\n", "OstreeGpgSignatureFormatFlags", sizeof(OstreeGpgSignatureFormatFlags), alignof(OstreeGpgSignatureFormatFlags)); + printf("%s;%zu;%zu\n", "OstreeMutableTreeClass", sizeof(OstreeMutableTreeClass), alignof(OstreeMutableTreeClass)); + printf("%s;%zu;%zu\n", "OstreeMutableTreeIter", sizeof(OstreeMutableTreeIter), alignof(OstreeMutableTreeIter)); + printf("%s;%zu;%zu\n", "OstreeObjectType", sizeof(OstreeObjectType), alignof(OstreeObjectType)); + printf("%s;%zu;%zu\n", "OstreeRepoCheckoutAtOptions", sizeof(OstreeRepoCheckoutAtOptions), alignof(OstreeRepoCheckoutAtOptions)); + printf("%s;%zu;%zu\n", "OstreeRepoCheckoutFilterResult", sizeof(OstreeRepoCheckoutFilterResult), alignof(OstreeRepoCheckoutFilterResult)); + printf("%s;%zu;%zu\n", "OstreeRepoCheckoutMode", sizeof(OstreeRepoCheckoutMode), alignof(OstreeRepoCheckoutMode)); + printf("%s;%zu;%zu\n", "OstreeRepoCheckoutOverwriteMode", sizeof(OstreeRepoCheckoutOverwriteMode), alignof(OstreeRepoCheckoutOverwriteMode)); + printf("%s;%zu;%zu\n", "OstreeRepoCommitFilterResult", sizeof(OstreeRepoCommitFilterResult), alignof(OstreeRepoCommitFilterResult)); + printf("%s;%zu;%zu\n", "OstreeRepoCommitIterResult", sizeof(OstreeRepoCommitIterResult), alignof(OstreeRepoCommitIterResult)); + printf("%s;%zu;%zu\n", "OstreeRepoCommitModifierFlags", sizeof(OstreeRepoCommitModifierFlags), alignof(OstreeRepoCommitModifierFlags)); + printf("%s;%zu;%zu\n", "OstreeRepoCommitState", sizeof(OstreeRepoCommitState), alignof(OstreeRepoCommitState)); + printf("%s;%zu;%zu\n", "OstreeRepoCommitTraverseFlags", sizeof(OstreeRepoCommitTraverseFlags), alignof(OstreeRepoCommitTraverseFlags)); + printf("%s;%zu;%zu\n", "OstreeRepoCommitTraverseIter", sizeof(OstreeRepoCommitTraverseIter), alignof(OstreeRepoCommitTraverseIter)); + printf("%s;%zu;%zu\n", "OstreeRepoFileClass", sizeof(OstreeRepoFileClass), alignof(OstreeRepoFileClass)); + printf("%s;%zu;%zu\n", "OstreeRepoFinderAvahiClass", sizeof(OstreeRepoFinderAvahiClass), alignof(OstreeRepoFinderAvahiClass)); + printf("%s;%zu;%zu\n", "OstreeRepoFinderConfigClass", sizeof(OstreeRepoFinderConfigClass), alignof(OstreeRepoFinderConfigClass)); + printf("%s;%zu;%zu\n", "OstreeRepoFinderInterface", sizeof(OstreeRepoFinderInterface), alignof(OstreeRepoFinderInterface)); + printf("%s;%zu;%zu\n", "OstreeRepoFinderMountClass", sizeof(OstreeRepoFinderMountClass), alignof(OstreeRepoFinderMountClass)); + printf("%s;%zu;%zu\n", "OstreeRepoFinderOverrideClass", sizeof(OstreeRepoFinderOverrideClass), alignof(OstreeRepoFinderOverrideClass)); + printf("%s;%zu;%zu\n", "OstreeRepoFinderResult", sizeof(OstreeRepoFinderResult), alignof(OstreeRepoFinderResult)); + printf("%s;%zu;%zu\n", "OstreeRepoFinderResultv", sizeof(OstreeRepoFinderResultv), alignof(OstreeRepoFinderResultv)); + printf("%s;%zu;%zu\n", "OstreeRepoListObjectsFlags", sizeof(OstreeRepoListObjectsFlags), alignof(OstreeRepoListObjectsFlags)); + printf("%s;%zu;%zu\n", "OstreeRepoListRefsExtFlags", sizeof(OstreeRepoListRefsExtFlags), alignof(OstreeRepoListRefsExtFlags)); + printf("%s;%zu;%zu\n", "OstreeRepoLockType", sizeof(OstreeRepoLockType), alignof(OstreeRepoLockType)); + printf("%s;%zu;%zu\n", "OstreeRepoMode", sizeof(OstreeRepoMode), alignof(OstreeRepoMode)); + printf("%s;%zu;%zu\n", "OstreeRepoPruneFlags", sizeof(OstreeRepoPruneFlags), alignof(OstreeRepoPruneFlags)); + printf("%s;%zu;%zu\n", "OstreeRepoPruneOptions", sizeof(OstreeRepoPruneOptions), alignof(OstreeRepoPruneOptions)); + printf("%s;%zu;%zu\n", "OstreeRepoPullFlags", sizeof(OstreeRepoPullFlags), alignof(OstreeRepoPullFlags)); + printf("%s;%zu;%zu\n", "OstreeRepoRemoteChange", sizeof(OstreeRepoRemoteChange), alignof(OstreeRepoRemoteChange)); + printf("%s;%zu;%zu\n", "OstreeRepoResolveRevExtFlags", sizeof(OstreeRepoResolveRevExtFlags), alignof(OstreeRepoResolveRevExtFlags)); + printf("%s;%zu;%zu\n", "OstreeRepoTransactionStats", sizeof(OstreeRepoTransactionStats), alignof(OstreeRepoTransactionStats)); + printf("%s;%zu;%zu\n", "OstreeRepoVerifyFlags", sizeof(OstreeRepoVerifyFlags), alignof(OstreeRepoVerifyFlags)); + printf("%s;%zu;%zu\n", "OstreeSePolicyRestoreconFlags", sizeof(OstreeSePolicyRestoreconFlags), alignof(OstreeSePolicyRestoreconFlags)); + printf("%s;%zu;%zu\n", "OstreeSignInterface", sizeof(OstreeSignInterface), alignof(OstreeSignInterface)); + printf("%s;%zu;%zu\n", "OstreeStaticDeltaGenerateOpt", sizeof(OstreeStaticDeltaGenerateOpt), alignof(OstreeStaticDeltaGenerateOpt)); + printf("%s;%zu;%zu\n", "OstreeStaticDeltaIndexFlags", sizeof(OstreeStaticDeltaIndexFlags), alignof(OstreeStaticDeltaIndexFlags)); + printf("%s;%zu;%zu\n", "OstreeSysrootDeployTreeOpts", sizeof(OstreeSysrootDeployTreeOpts), alignof(OstreeSysrootDeployTreeOpts)); + printf("%s;%zu;%zu\n", "OstreeSysrootSimpleWriteDeploymentFlags", sizeof(OstreeSysrootSimpleWriteDeploymentFlags), alignof(OstreeSysrootSimpleWriteDeploymentFlags)); + printf("%s;%zu;%zu\n", "OstreeSysrootUpgraderFlags", sizeof(OstreeSysrootUpgraderFlags), alignof(OstreeSysrootUpgraderFlags)); + printf("%s;%zu;%zu\n", "OstreeSysrootUpgraderPullFlags", sizeof(OstreeSysrootUpgraderPullFlags), alignof(OstreeSysrootUpgraderPullFlags)); + printf("%s;%zu;%zu\n", "OstreeSysrootWriteDeploymentsOpts", sizeof(OstreeSysrootWriteDeploymentsOpts), alignof(OstreeSysrootWriteDeploymentsOpts)); + return 0; +} diff --git a/rust-bindings/sys/tests/manual.h b/rust-bindings/sys/tests/manual.h new file mode 100644 index 0000000000..0e2e16c3bf --- /dev/null +++ b/rust-bindings/sys/tests/manual.h @@ -0,0 +1,9 @@ +// Feel free to edit this file, it won't be regenerated by gir generator unless removed. +#include <ostree.h> + +// hack to build and test on versions of libostree < 2019.2 +#if !OSTREE_CHECK_VERSION(2019, 2) +# define OSTREE_REPO_LIST_REFS_EXT_EXCLUDE_MIRRORS 4 +# define OSTREE_REPO_REMOTE_CHANGE_REPLACE 4 +# define OSTREE_REPO_RESOLVE_REV_EXT_LOCAL_ONLY 1 +#endif diff --git a/rust-bindings/tests/core/mod.rs b/rust-bindings/tests/core/mod.rs new file mode 100644 index 0000000000..7ac13cf208 --- /dev/null +++ b/rust-bindings/tests/core/mod.rs @@ -0,0 +1,13 @@ +use crate::util::*; +use std::error::Error; + +#[test] +fn variant_types() -> Result<(), Box<dyn Error>> { + let tr = TestRepo::new(); + let commit_checksum = tr.test_commit("test"); + let repo = &tr.repo; + let commit_v = repo.load_variant(ostree::ObjectType::Commit, commit_checksum.as_str())?; + let commit = commit_v.get::<ostree::CommitVariantType>().unwrap(); + assert_eq!(commit.3, "Test Commit"); + Ok(()) +} diff --git a/rust-bindings/tests/data/test.tar b/rust-bindings/tests/data/test.tar new file mode 100644 index 0000000000..fd39eda107 Binary files /dev/null and b/rust-bindings/tests/data/test.tar differ diff --git a/rust-bindings/tests/functions/mod.rs b/rust-bindings/tests/functions/mod.rs new file mode 100644 index 0000000000..9fa3a91841 --- /dev/null +++ b/rust-bindings/tests/functions/mod.rs @@ -0,0 +1,71 @@ +use crate::util::TestRepo; +use gio::NONE_CANCELLABLE; +use ostree::{checksum_file_from_input, ObjectType}; + +#[test] +fn list_repo_objects() { + let repo = TestRepo::new(); + let commit_checksum = repo.test_commit("test"); + let mut dirtree_cnt = 0; + let mut dirmeta_cnt = 0; + let mut file_cnt = 0; + let mut commit_cnt = 0; + + let objects = repo + .repo + .list_objects(ffi::OSTREE_REPO_LIST_OBJECTS_ALL, NONE_CANCELLABLE) + .expect("List Objects"); + for (object, _items) in objects { + match object.object_type() { + ObjectType::DirTree => { + dirtree_cnt += 1; + } + ObjectType::DirMeta => { + dirmeta_cnt += 1; + } + ObjectType::File => { + file_cnt += 1; + } + ObjectType::Commit => { + assert_eq!(commit_checksum.to_string(), object.checksum()); + commit_cnt += 1; + } + x => { + panic!("unexpected object type {}", x); + } + } + } + assert_eq!(dirtree_cnt, 2); + assert_eq!(dirmeta_cnt, 1); + assert_eq!(file_cnt, 1); + assert_eq!(commit_cnt, 1); +} + +#[test] +fn should_checksum_file_from_input() { + let repo = TestRepo::new(); + let commit_checksum = repo.test_commit("test"); + + let objects = repo + .repo + .traverse_commit(&commit_checksum, -1, NONE_CANCELLABLE) + .expect("traverse commit"); + for obj in objects { + if obj.object_type() != ObjectType::File { + continue; + } + let (stream, file_info, xattrs) = repo + .repo + .load_file(obj.checksum(), NONE_CANCELLABLE) + .expect("load file"); + let result = checksum_file_from_input( + file_info.as_ref().unwrap(), + xattrs.as_ref(), + stream.as_ref(), + ObjectType::File, + NONE_CANCELLABLE, + ) + .expect("checksum file from input"); + assert_eq!(result.to_string(), obj.checksum()); + } +} diff --git a/rust-bindings/tests/repo/checkout_at.rs b/rust-bindings/tests/repo/checkout_at.rs new file mode 100644 index 0000000000..9402864295 --- /dev/null +++ b/rust-bindings/tests/repo/checkout_at.rs @@ -0,0 +1,108 @@ +use crate::util::*; +use gio::NONE_CANCELLABLE; +use ostree::*; +use std::os::unix::io::AsRawFd; + +#[test] +fn should_checkout_at_with_none_options() { + let test_repo = TestRepo::new(); + let checksum = test_repo.test_commit("test"); + let checkout_dir = tempfile::tempdir().expect("checkout dir"); + + let dirfd = openat::Dir::open(checkout_dir.path()).expect("openat"); + test_repo + .repo + .checkout_at( + None, + dirfd.as_raw_fd(), + "test-checkout", + &checksum, + NONE_CANCELLABLE, + ) + .expect("checkout at"); + + assert_test_file(checkout_dir.path()); +} + +#[test] +fn should_checkout_at_with_default_options() { + let test_repo = TestRepo::new(); + let checksum = test_repo.test_commit("test"); + let checkout_dir = tempfile::tempdir().expect("checkout dir"); + + let dirfd = openat::Dir::open(checkout_dir.path()).expect("openat"); + test_repo + .repo + .checkout_at( + Some(&RepoCheckoutAtOptions::default()), + dirfd.as_raw_fd(), + "test-checkout", + &checksum, + NONE_CANCELLABLE, + ) + .expect("checkout at"); + + assert_test_file(checkout_dir.path()); +} + +#[test] +fn should_checkout_at_with_options() { + let test_repo = TestRepo::new(); + let checksum = test_repo.test_commit("test"); + let checkout_dir = tempfile::tempdir().expect("checkout dir"); + + let dirfd = openat::Dir::open(checkout_dir.path()).expect("openat"); + test_repo + .repo + .checkout_at( + Some(&RepoCheckoutAtOptions { + mode: RepoCheckoutMode::User, + overwrite_mode: RepoCheckoutOverwriteMode::AddFiles, + enable_fsync: true, + devino_to_csum_cache: Some(RepoDevInoCache::new()), + ..Default::default() + }), + dirfd.as_raw_fd(), + "test-checkout", + &checksum, + NONE_CANCELLABLE, + ) + .expect("checkout at"); + + assert_test_file(checkout_dir.path()); +} + +#[test] +#[cfg(feature = "v2018_2")] +fn should_checkout_at_with_filter() { + use std::path::Path; + + let test_repo = TestRepo::new(); + let checksum = test_repo.test_commit("test"); + let checkout_dir = tempfile::tempdir().expect("checkout dir"); + + let dirfd = openat::Dir::open(checkout_dir.path()).expect("openat"); + test_repo + .repo + .checkout_at( + Some(&RepoCheckoutAtOptions { + filter: RepoCheckoutFilter::new(|_repo, path, _stat| { + if path == Path::new("/testdir/testfile") { + RepoCheckoutFilterResult::Skip + } else { + RepoCheckoutFilterResult::Allow + } + }), + ..Default::default() + }), + dirfd.as_raw_fd(), + "test-checkout", + &checksum, + NONE_CANCELLABLE, + ) + .expect("checkout at"); + + let testdir = checkout_dir.path().join("test-checkout").join("testdir"); + assert!(std::fs::read_dir(&testdir).is_ok()); + assert!(std::fs::File::open(&testdir.join("testfile")).is_err()); +} diff --git a/rust-bindings/tests/repo/mod.rs b/rust-bindings/tests/repo/mod.rs new file mode 100644 index 0000000000..703dc73586 --- /dev/null +++ b/rust-bindings/tests/repo/mod.rs @@ -0,0 +1,186 @@ +use crate::util::*; +use ostree::gio::NONE_CANCELLABLE; +use ostree::prelude::*; +use ostree::{ObjectName, ObjectType}; + +#[cfg(feature = "v2016_8")] +mod checkout_at; + +#[test] +fn should_commit_content_to_repo_and_list_refs_again() { + let test_repo = TestRepo::new(); + + assert!(test_repo.repo.require_rev("nosuchrev").is_err()); + + let mtree = create_mtree(&test_repo.repo); + let checksum = commit(&test_repo.repo, &mtree, "test"); + + assert_eq!(test_repo.repo.require_rev("test").unwrap(), checksum); + + let repo = ostree::Repo::new_for_path(test_repo.dir.path()); + repo.open(NONE_CANCELLABLE).expect("OSTree test_repo"); + let refs = repo + .list_refs(None, NONE_CANCELLABLE) + .expect("failed to list refs"); + assert_eq!(1, refs.len()); + assert_eq!(checksum, refs["test"]); +} + +#[test] +#[cfg(feature = "cap-std-apis")] +fn cap_std_commit() { + let test_repo = CapTestRepo::new(); + + assert!(test_repo.dir.exists("config")); + // Also test re-acquiring a new dfd + assert!(test_repo.repo.dfd_as_dir().unwrap().exists("config")); + + assert!(test_repo.repo.require_rev("nosuchrev").is_err()); + + let mtree = create_mtree(&test_repo.repo); + let checksum = commit(&test_repo.repo, &mtree, "test"); + + assert_eq!(test_repo.repo.require_rev("test").unwrap(), checksum); + + let repo2 = ostree::Repo::open_at_dir(&test_repo.dir, ".").unwrap(); + let refs = repo2 + .list_refs(None, NONE_CANCELLABLE) + .expect("failed to list refs"); + assert_eq!(1, refs.len()); + assert_eq!(checksum, refs["test"]); +} + +#[test] +fn repo_traverse_and_read() { + let test_repo = TestRepo::new(); + let checksum = test_repo.test_commit("test"); + + let objects = test_repo + .repo + .traverse_commit(&checksum, -1, NONE_CANCELLABLE) + .expect("traverse commit"); + + assert_eq!( + maplit::hashset!( + ObjectName::new( + "89f84ca9854a80e85b583e46a115ba4985254437027bad34f0b113219323d3f8", + ObjectType::File + ), + ObjectName::new( + "5280a884f930cae329e2e39d52f2c8e910c2ef4733216b67679db32a2b56c4db", + ObjectType::DirTree + ), + ObjectName::new( + "c81acde323d73f8639fc84f1ded17bbafc415e645f845e9f3b16a4906857c2d4", + ObjectType::DirTree + ), + ObjectName::new( + "ad49a0f4e3bc165361b6d17e8a865d479b373ee67d89ac6f0ce871f27da1be6d", + ObjectType::DirMeta + ), + ObjectName::new(checksum, ObjectType::Commit) + ), + objects + ); + + let dirmeta = test_repo + .repo + .read_dirmeta("ad49a0f4e3bc165361b6d17e8a865d479b373ee67d89ac6f0ce871f27da1be6d") + .unwrap(); + // Right now, the uid/gid are actually that of the test runner + assert_eq!(dirmeta.mode, 0o40750); + + let (finfo, _xattrs) = test_repo + .repo + .query_file( + "89f84ca9854a80e85b583e46a115ba4985254437027bad34f0b113219323d3f8", + NONE_CANCELLABLE, + ) + .unwrap(); + assert_eq!(finfo.size(), 5); +} + +#[test] +fn should_checkout_tree() { + let test_repo = TestRepo::new(); + let _ = test_repo.test_commit("test"); + + let checkout_dir = tempfile::tempdir().expect("checkout dir"); + let file = test_repo + .repo + .read_commit("test", NONE_CANCELLABLE) + .expect("read commit") + .0 + .downcast::<ostree::RepoFile>() + .expect("RepoFile"); + let info = file + .query_info("*", gio::FileQueryInfoFlags::NONE, NONE_CANCELLABLE) + .expect("file info"); + test_repo + .repo + .checkout_tree( + ostree::RepoCheckoutMode::User, + ostree::RepoCheckoutOverwriteMode::None, + &gio::File::for_path(checkout_dir.path().join("test-checkout")), + &file, + &info, + NONE_CANCELLABLE, + ) + .expect("checkout tree"); + + assert_test_file(checkout_dir.path()); +} + +#[test] +fn should_write_content_to_repo() { + let src = TestRepo::new(); + let mtree = create_mtree(&src.repo); + let checksum = commit(&src.repo, &mtree, "test"); + + let dest = TestRepo::new(); + let objects = src + .repo + .traverse_commit(&checksum, -1, NONE_CANCELLABLE) + .expect("traverse"); + for obj in objects { + match obj.object_type() { + ObjectType::File => copy_file(&src, &dest, &obj), + _ => copy_metadata(&src, &dest, &obj), + } + } +} + +#[test] +#[cfg(feature = "v2016_4")] +fn repo_file() { + use std::os::unix::fs::MetadataExt; + let test_repo = TestRepo::new(); + let m1 = test_repo.repo.dfd_as_file().unwrap().metadata().unwrap(); + let m2 = test_repo.repo.dfd_as_file().unwrap().metadata().unwrap(); + assert_eq!(m1.dev(), m2.dev()); + assert_eq!(m1.ino(), m2.ino()); +} + +fn copy_file(src: &TestRepo, dest: &TestRepo, obj: &ObjectName) { + let (stream, len) = src + .repo + .load_object_stream(obj.object_type(), obj.checksum(), NONE_CANCELLABLE) + .expect("load object stream"); + let out_csum = dest + .repo + .write_content(None, &stream, len, NONE_CANCELLABLE) + .expect("write content"); + assert_eq!(out_csum.to_string(), obj.checksum()); +} + +fn copy_metadata(src: &TestRepo, dest: &TestRepo, obj: &ObjectName) { + let data = src + .repo + .load_variant(obj.object_type(), obj.checksum()) + .expect("load variant"); + let out_csum = dest + .repo + .write_metadata(obj.object_type(), None, &data, NONE_CANCELLABLE) + .expect("write metadata"); + assert_eq!(out_csum.to_string(), obj.checksum()); +} diff --git a/rust-bindings/tests/sign/mod.rs b/rust-bindings/tests/sign/mod.rs new file mode 100644 index 0000000000..5df49d6364 --- /dev/null +++ b/rust-bindings/tests/sign/mod.rs @@ -0,0 +1,21 @@ +use ostree::prelude::*; +use ostree::{gio, glib}; + +#[test] +fn sign_api_should_work() { + let dummy_sign = ostree::Sign::by_name("dummy").unwrap(); + assert_eq!(dummy_sign.name().unwrap(), "dummy"); + + let result = ostree::prelude::SignExt::data( + &dummy_sign, + &glib::Bytes::from_static(b"1234"), + gio::NONE_CANCELLABLE, + ); + assert!(result.is_err()); + + let result = dummy_sign.data_verify(&glib::Bytes::from_static(b"1234"), &"1234".to_variant()); + assert!(result.is_err()); + + let result = ostree::Sign::by_name("NOPE"); + assert!(result.is_err()); +} diff --git a/rust-bindings/tests/tests.rs b/rust-bindings/tests/tests.rs new file mode 100644 index 0000000000..18076002b4 --- /dev/null +++ b/rust-bindings/tests/tests.rs @@ -0,0 +1,6 @@ +mod core; +mod functions; +mod repo; +#[cfg(feature = "v2020_2")] +mod sign; +mod util; diff --git a/rust-bindings/tests/util/mod.rs b/rust-bindings/tests/util/mod.rs new file mode 100644 index 0000000000..28cca92694 --- /dev/null +++ b/rust-bindings/tests/util/mod.rs @@ -0,0 +1,98 @@ +use gio::NONE_CANCELLABLE; +use glib::prelude::*; +use glib::GString; +use std::path::Path; + +#[derive(Debug)] +pub struct TestRepo { + pub dir: tempfile::TempDir, + pub repo: ostree::Repo, +} + +impl TestRepo { + pub fn new() -> TestRepo { + TestRepo::new_with_mode(ostree::RepoMode::Archive) + } + + pub fn new_with_mode(repo_mode: ostree::RepoMode) -> TestRepo { + let dir = tempfile::tempdir().expect("temp repo dir"); + let repo = ostree::Repo::new_for_path(dir.path()); + repo.create(repo_mode, NONE_CANCELLABLE) + .expect("OSTree repo"); + TestRepo { dir, repo } + } + + pub fn test_commit(&self, ref_: &str) -> GString { + let mtree = create_mtree(&self.repo); + commit(&self.repo, &mtree, ref_) + } +} + +#[derive(Debug)] +#[cfg(feature = "cap-std-apis")] +pub struct CapTestRepo { + pub dir: cap_tempfile::TempDir, + pub repo: ostree::Repo, +} + +#[cfg(feature = "cap-std-apis")] +impl CapTestRepo { + pub fn new() -> Self { + Self::new_with_mode(ostree::RepoMode::Archive) + } + + pub fn new_with_mode(repo_mode: ostree::RepoMode) -> Self { + let dir = cap_tempfile::tempdir(cap_std::ambient_authority()).unwrap(); + let repo = ostree::Repo::create_at_dir(&dir, ".", repo_mode, None).expect("repo create"); + Self { dir, repo } + } +} + +pub fn create_mtree(repo: &ostree::Repo) -> ostree::MutableTree { + let mtree = ostree::MutableTree::new(); + assert_eq!(mtree.copy_files().len(), 0); + assert_eq!(mtree.copy_subdirs().len(), 0); + let file = gio::File::for_path( + Path::new(env!("CARGO_MANIFEST_DIR")) + .join("tests") + .join("data") + .join("test.tar"), + ); + repo.write_archive_to_mtree(&file, &mtree, None, true, NONE_CANCELLABLE) + .expect("test mtree"); + mtree +} + +pub fn commit(repo: &ostree::Repo, mtree: &ostree::MutableTree, ref_: &str) -> GString { + let txn = repo + .auto_transaction(NONE_CANCELLABLE) + .expect("prepare transaction"); + let repo_file = txn + .repo() + .write_mtree(mtree, NONE_CANCELLABLE) + .expect("write mtree") + .downcast::<ostree::RepoFile>() + .unwrap(); + let checksum = repo + .write_commit( + None, + "Test Commit".into(), + None, + None, + &repo_file, + NONE_CANCELLABLE, + ) + .expect("write commit"); + repo.transaction_set_ref(None, ref_, checksum.as_str().into()); + txn.commit(NONE_CANCELLABLE).expect("commit transaction"); + checksum +} + +pub fn assert_test_file(checkout: &Path) { + let testfile_path = checkout + .join("test-checkout") + .join("testdir") + .join("testfile"); + let testfile_contents = std::fs::read_to_string(testfile_path).expect("test file"); + assert_eq!("test\n", testfile_contents); +} diff --git a/tests/inst/.gitignore b/tests/inst/.gitignore new file mode 100644 index 0000000000..1e7caa9ea8 --- /dev/null +++ b/tests/inst/.gitignore @@ -0,0 +1,2 @@ +Cargo.lock +target/ diff --git a/tests/inst/Cargo.toml b/tests/inst/Cargo.toml index 70e56dc585..cf9c2dcc01 100644 --- a/tests/inst/Cargo.toml +++ b/tests/inst/Cargo.toml @@ -4,6 +4,8 @@ version = "0.1.0" authors = ["Colin Walters <walters@verbum.org>"] edition = "2018" +[workspace] + [[bin]] name = "ostree-test" path = "src/insttestmain.rs" diff --git a/tests/kolainst/Makefile b/tests/kolainst/Makefile index 5dc18281a5..acfdc3b71f 100644 --- a/tests/kolainst/Makefile +++ b/tests/kolainst/Makefile @@ -12,6 +12,6 @@ all: install: install -D -m 0644 -t $(KOLA_TESTDIR) $(LIBSCRIPTS) for x in $(TESTDIRS); do rsync -rlv ./$${x} $(KOLA_TESTDIR)/; done - install -D -m 0755 -t $(KOLA_TESTDIR)/nondestructive-rs ../../target/release/ostree-test + install -D -m 0755 -t $(KOLA_TESTDIR)/nondestructive-rs ../inst/target/release/ostree-test install -D -m 0644 destructive-stamp.ign $(KOLA_TESTDIR)/destructive-rs/config.ign ./install-wrappers.sh destructive-list.txt $(KOLA_TESTDIR)/destructive-rs