diff options
Diffstat (limited to 'doc/udisks2-docs.xml')
| -rw-r--r-- | doc/udisks2-docs.xml | 463 |
1 files changed, 0 insertions, 463 deletions
diff --git a/doc/udisks2-docs.xml b/doc/udisks2-docs.xml deleted file mode 100644 index df749f7..0000000 --- a/doc/udisks2-docs.xml +++ /dev/null @@ -1,463 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" -"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -<!ENTITY version SYSTEM "version.xml"> -]> -<book id="udisks" xmlns:xi="http://www.w3.org/2003/XInclude"> - <bookinfo> - <title>UDisks Reference Manual</title> - <releaseinfo> - For version &version; — the latest version of this - documentation can be found at <ulink role="online-location" - url="http://udisks.freedesktop.org/docs/latest/">http://udisks.freedesktop.org/docs/latest/</ulink>. - </releaseinfo> - </bookinfo> - - <part id="overview"> - <title>Manual pages and Overview</title> - <xi:include href="man/udisks.xml"/> - <xi:include href="man/udisksd.xml"/> - <xi:include href="man/udisksctl.xml"/> - </part> - - <part id="ref-dbus"> - <title>D-Bus API Reference</title> - <chapter id="ref-dbus-overview"> - <title>Overview</title> - <sect1 id="ref-dbus-well-known-name"> - <title>The org.freedesktop.UDisks2 bus name</title> - <para> - The D-Bus name <literal>org.freedesktop.UDisks2</literal> on - the system bus is used by the UDisks Daemon, <link - linkend="udisksd.8">udisksd</link>. If this daemon isn't - running, it will be started if D-Bus messages are sent to - the name. - </para> - </sect1> - <sect1 id="ref-dbus-udisks2-well-known-object"> - <title>The /org/freedesktop/UDisks2 object</title> - <para> - The process that owns the well-known D-Bus name <link - linkend="ref-dbus-well-known-name">org.freedesktop.UDisks2</link> - on the system bus (typically <link - linkend="udisksd.8">udisksd</link>) exports an object at the - well-known path <literal>/org/freedesktop/UDisks2</literal>. - This object implements the <ulink - url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink> - interface and should be used by clients to discover other - objects. - </para> - </sect1> - <sect1 id="ref-dbus-manager-well-known-object"> - <title>The /org/freedesktop/UDisks2/Manager object</title> - <para> - The object at the path - <literal>/org/freedesktop/UDisks2/Manager</literal> - implements the <link - linkend="gdbus-interface-org-freedesktop-UDisks2-Manager.top_of_page">org.freedesktop.UDisks2.Manager</link> - D-Bus interface. This object can be used to inspect and - manipulate global state. - </para> - </sect1> - - <sect1 id="ref-dbus-block-devices"> - <title>The /org/freedesktop/UDisks2/block_devices/* objects</title> - <para> - Objects with object paths starting with - <literal>/org/freedesktop/UDisks2/block_devices/</literal> - all represent <ulink url="http://en.wikipedia.org/wiki/Block_device#Block_devices">block devices</ulink>. - Such objects implement the - <link linkend="gdbus-interface-org-freedesktop-UDisks2-Block.top_of_page">org.freedesktop.UDisks2.Block</link> - D-Bus interface and may optionally implement other D-Bus interfaces such as - <link linkend="gdbus-interface-org-freedesktop-UDisks2-Filesystem.top_of_page">org.freedesktop.UDisks2.Filesystem</link>, - <link linkend="gdbus-interface-org-freedesktop-UDisks2-Partition.top_of_page">org.freedesktop.UDisks2.Partition</link> or - <link linkend="gdbus-interface-org-freedesktop-UDisks2-Loop.top_of_page">org.freedesktop.UDisks2.Loop</link> depending on the block device in question. - </para> - <para> - Note that interfaces may be added and removed at - run-time. For example, if a block device is full of zeroes - (or, at least, have zeroes in the known metadata areas), it - will not intially implement the <link - linkend="gdbus-interface-org-freedesktop-UDisks2-Filesystem.top_of_page">org.freedesktop.UDisks2.Filesystem</link> - interface; however, if a filesystem is later created on the device - (using, say, the - <citerefentry> - <refentrytitle>mkfs</refentrytitle><manvolnum>8</manvolnum> - </citerefentry> - command) and the filesystem is recognized by the OS (specifically, recognized by - <citerefentry> - <refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum> - </citerefentry> and its device probers), the object will gain the interface. If the device is later zeroed or formatted for use as e.g. swap-space, it will lose the - <link linkend="gdbus-interface-org-freedesktop-UDisks2-Filesystem.top_of_page">org.freedesktop.UDisks2.Filesystem</link> - interface. - </para> - </sect1> - - <sect1 id="ref-dbus-drives"> - <title>The /org/freedesktop/UDisks2/drives/* objects</title> - <para> - Objects with object paths starting with - <literal>/org/freedesktop/UDisks2/drives/</literal> - all represent <ulink url="http://en.wikipedia.org/wiki/Disk_drive">disk drives</ulink>, - typically physical disk drives. - Such objects implement the - <link linkend="gdbus-interface-org-freedesktop-UDisks2-Drive.top_of_page">org.freedesktop.UDisks2.Drive</link> - D-Bus interface and may optionally implement other D-Bus interfaces such as - <link linkend="gdbus-interface-org-freedesktop-UDisks2-Drive-Ata.top_of_page">org.freedesktop.UDisks2.Drive.Ata</link> depending on the drive in question. - </para> - <para> - A drive object should not to be confused with - <link linkend="ref-dbus-block-devices">block device</link> - objects (which are used for low-level block devices the OS - knows about). For example, if <filename>/dev/sda</filename> - and <filename>/dev/sdb</filename> are block devices for two - paths to the same drive, there will be only drive object but - two block device objects. - </para> - </sect1> - - <sect1 id="ref-dbus-md-raid"> - <title>The /org/freedesktop/UDisks2/mdraid/* objects</title> - <para> - Objects with object paths starting with - <literal>/org/freedesktop/UDisks2/mdraid/</literal> - represent <ulink url="https://raid.wiki.kernel.org/index.php/Linux_Raid">Linux Software RAID arrays</ulink>. - Such objects implement the - <link linkend="gdbus-interface-org-freedesktop-UDisks2-MDRaid.top_of_page">org.freedesktop.UDisks2.MDRaid</link> - D-Bus interface. - </para> - <para> - These objects should not to be confused with - <link linkend="ref-dbus-block-devices">block device</link> - objects (which are used for low-level block devices the OS - knows about). - </para> - </sect1> - - <sect1 id="ref-dbus-jobs"> - <title>The /org/freedesktop/UDisks2/jobs/* objects</title> - <para> - Objects with object paths starting with - <literal>/org/freedesktop/UDisks2/jobs/</literal> all - represent long-running tasks, typically initiated by the - user and are guaranteed to implement the - <link linkend="gdbus-interface-org-freedesktop-UDisks2-Job.top_of_page">org.freedesktop.UDisks2.Job</link> - D-Bus interface. - </para> - </sect1> - - <sect1 id="udisks-polkit-actions"> - <title>Authorization Checks</title> - <para> - Many methods and operations offered by udisks requires the - calling user to be sufficiently authorized. Whether the user - is authorized is checked using <ulink - url="http://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html">polkit</ulink> - allowing the administrator to configure fine-grained permissions via - polkit authorization rules. - </para> - <para> - There is not necessarily a one-to-one relationship between - D-Bus methods and polkit actions - typically the - relationship is more complicated and depends on both the - context of the process invoking the method, the object the - method is acting on and possibly more factors. For example, - the <link - linkend="gdbus-method-org-freedesktop-UDisks2-Filesystem.Mount">Filesystem.Mount()</link> - method call may check that the caller is authorized for one - of the four actions - <emphasis>org.freedesktop.udisks2.filesystem-mount</emphasis>, - <emphasis>org.freedesktop.udisks2.filesystem-mount-system</emphasis>, - <emphasis>org.freedesktop.udisks2.filesystem-mount-other-seat</emphasis> - or - <emphasis>org.freedesktop.udisks2.filesystem-mount-fstab</emphasis> - depending on circumstances. - </para> - <para> - Often there will be two polkit actions for one operation - - one for so-called <quote>system devices</quote> and one for - non-system devices. In this context <quote>system - device</quote> refers to the value of the <link - linkend="gdbus-property-org-freedesktop-UDisks2-Block.HintSystem">Block:HintSystem</link> - D-Bus property and is normally only - <constant>TRUE</constant> for devices not considered - <quote>removable</quote> (devices considered removable - include USB attached storage, Flash media and optical - drives). See <xref linkend="udisks.8"/> for how to control - if a device is considered a system device. - </para> - <para> - The polkit actions are not considered stable and may change - from release to release so administrators should take notice - when upgrading from one version of udisks to another. For - example, polkit authorization rules may need to be updated - to match an updated policy. - </para> - <para> - See <xref linkend="udisks-polkit-details"/> for the - variables that can be used to assist in determining if the - caller is authorized (note that each variable may not be set - for request). For example, a polkit authorization rule for - any of the - <emphasis>org.freedesktop.udisks2.filesystem-mount*</emphasis> - actions can use the <parameter>device</parameter> variable - to determine if the caller is authorized to mount a specific - block device. - </para> - - <table frame="all" id="udisks-polkit-details"> - <title>Known polkit variables</title> - <tgroup cols="2" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>key</entry> - <entry>value</entry> - </row> - </thead> - <tbody> - <row> - <entry><parameter>device</parameter></entry> - <entry>If the object is a block device, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Block.PreferredDevice">Block:PreferredDevice</link> property. If set, this is guaranteed to be a device file, for example <quote>/dev/vg_lucifer/lv_root</quote> or <quote>/dev/sda1</quote>. If the object is not a block device, this is not set.</entry> - </row> - <row> - <entry><parameter>drive</parameter></entry> - <entry>Like the <parameter>device</parameter> variable, but if the object is also a drive, this variable includes Vital Product Data about the drive such as the vendor and model identifiers (if available), for example <quote>INTEL SSDSA2MH080G1GC (/dev/sda1)</quote>. Otherwise is just set to the same value as <parameter>device</parameter>. If the object is not a block device, this is not set (it is however set if the object is a block device but not a drive).</entry> - </row> - - <row> - <entry><parameter>drive.wwn</parameter></entry> - <entry>If the object is a drive (or a block device that is part of a drive), this is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.WWN">Drive:WWN</link> property.</entry> - </row> - <row> - <entry><parameter>drive.serial</parameter></entry> - <entry>If the object is a drive (or a block device that is part of a drive), this is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.Serial">Drive:Serial</link> property.</entry> - </row> - <row> - <entry><parameter>drive.vendor</parameter></entry> - <entry>If the object is a drive (or a block device that is part of a drive), this is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.Vendor">Drive:Vendor</link> property.</entry> - </row> - <row> - <entry><parameter>drive.model</parameter></entry> - <entry>If the object is a drive (or a block device that is part of a drive), this is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.Model">Drive:Model</link> property.</entry> - </row> - <row> - <entry><parameter>drive.revision</parameter></entry> - <entry>If the object is a drive (or a block device that is part of a drive), this is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.Revision">Drive:Revision</link> property.</entry> - </row> - <row> - <entry><parameter>drive.removable</parameter></entry> - <entry>If the object is a drive (or a block device that is part of a drive), this is set to the string <quote>true</quote> only if the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.Removable">Drive:Removable</link> property is <constant>TRUE</constant>.</entry> - </row> - <row> - <entry><parameter>drive.removable.bus</parameter></entry> - <entry>If the object is a drive (or a block device that is part of a drive), this is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.ConnectionBus">Drive:ConnectionBus</link> property. This variable is set only if the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.Removable">Drive:Removable</link> property is <constant>TRUE</constant>.</entry> - </row> - <row> - <entry><parameter>drive.removable.media</parameter></entry> - <entry>If the object is a drive (or a block device that is part of a drive), this is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.MediaCompatibility">Drive:MediaCompatibility</link> property. This variable is set only if the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.Removable">Drive:Removable</link> property is <constant>TRUE</constant>.</entry> - </row> - - <row> - <entry><parameter>id.type</parameter></entry> - <entry>If the object is a block device, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Block.IdType">Block:IdType</link> property.</entry> - </row> - <row> - <entry><parameter>id.usage</parameter></entry> - <entry>If the object is a block device, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Block.IdUsage">Block:IdUsage</link> property.</entry> - </row> - <row> - <entry><parameter>id.version</parameter></entry> - <entry>If the object is a block device, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Block.IdVersion">Block:IdVersion</link> property.</entry> - </row> - <row> - <entry><parameter>id.label</parameter></entry> - <entry>If the object is a block device, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Block.IdLabel">Block:IdLabel</link> property.</entry> - </row> - <row> - <entry><parameter>id.uuid</parameter></entry> - <entry>If the object is a block device, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Block.IdUUID">Block:IdUUID</link> property.</entry> - </row> - - <row> - <entry><parameter>partition.number</parameter></entry> - <entry>If the object is a partition, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Partition.Number">Partition:Number</link> property.</entry> - </row> - <row> - <entry><parameter>partition.type</parameter></entry> - <entry>If the object is a partition, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Partition.Type">Partition:Type</link> property.</entry> - </row> - <row> - <entry><parameter>partition.flags</parameter></entry> - <entry>If the object is a partition, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Partition.Flags">Partition:Flags</link> property.</entry> - </row> - <row> - <entry><parameter>partition.name</parameter></entry> - <entry>If the object is a partition, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Partition.Name">Partition:Name</link> property.</entry> - </row> - <row> - <entry><parameter>partition.uuid</parameter></entry> - <entry>If the object is a partition, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Partition.UUID">Partition:UUID</link> property.</entry> - </row> - - </tbody> - </tgroup> - </table> - - <para> - For reference, the polkit actions defined by udisks &version; - are included here: - <informalexample id="udisks-polkit-actions-file"><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../data/org.freedesktop.udisks2.policy.in"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></informalexample> - </para> - </sect1> - - <sect1 id="udisks-std-options"> - <title>The <parameter>options</parameter> parameter</title> - <para> - Many method calls take a parameter of type - <link linkend='G-VARIANT-TYPE-VARDICT:CAPS'>'a{sv}'</link> - that is normally called <parameter>options</parameter>. - The following table lists well-known options: - </para> - <table frame='all'> - <title>Well-known options</title> - <tgroup cols='3' align='left' colsep='1' rowsep='1'> - <thead> - <row> - <entry>Option name</entry> - <entry>Value type</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>auth.no_user_interaction</entry> - <entry><link linkend="G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</link></entry> - <entry> - If set to <constant>TRUE</constant>, then no user - interaction will happen when checking if the method - call is authorized. - </entry> - </row> - </tbody> - </tgroup> - </table> - </sect1> - - </chapter> - - <chapter> - <title>D-Bus Interfaces</title> - <xi:include href="../udisks/udisks-generated-doc-org.freedesktop.UDisks2.Manager.xml"/> - <xi:include href="../udisks/udisks-generated-doc-org.freedesktop.UDisks2.Drive.xml"/> - <xi:include href="../udisks/udisks-generated-doc-org.freedesktop.UDisks2.Drive.Ata.xml"/> - <xi:include href="../udisks/udisks-generated-doc-org.freedesktop.UDisks2.MDRaid.xml"/> - <xi:include href="../udisks/udisks-generated-doc-org.freedesktop.UDisks2.Block.xml"/> - <xi:include href="../udisks/udisks-generated-doc-org.freedesktop.UDisks2.Partition.xml"/> - <xi:include href="../udisks/udisks-generated-doc-org.freedesktop.UDisks2.PartitionTable.xml"/> - <xi:include href="../udisks/udisks-generated-doc-org.freedesktop.UDisks2.Filesystem.xml"/> - <xi:include href="../udisks/udisks-generated-doc-org.freedesktop.UDisks2.Swapspace.xml"/> - <xi:include href="../udisks/udisks-generated-doc-org.freedesktop.UDisks2.Encrypted.xml"/> - <xi:include href="../udisks/udisks-generated-doc-org.freedesktop.UDisks2.Loop.xml"/> - <xi:include href="../udisks/udisks-generated-doc-org.freedesktop.UDisks2.Job.xml"/> - </chapter> - </part> - - <part id="ref-library"> - <title>Library API Reference</title> - <xi:include href="xml/udisksclient.xml"/> - <xi:include href="xml/udisksobjectinfo.xml"/> - <xi:include href="xml/udiskserror.xml"/> - <chapter id="ref-library-generated"> - <title>Generated Code</title> - <xi:include href="xml/UDisksObject.xml"/> - <xi:include href="xml/UDisksObjectManagerClient.xml"/> - <xi:include href="xml/UDisksManager.xml"/> - <xi:include href="xml/UDisksDrive.xml"/> - <xi:include href="xml/UDisksDriveAta.xml"/> - <xi:include href="xml/UDisksMDRaid.xml"/> - <xi:include href="xml/UDisksJob.xml"/> - <xi:include href="xml/UDisksBlock.xml"/> - <xi:include href="xml/UDisksPartition.xml"/> - <xi:include href="xml/UDisksPartitionTable.xml"/> - <xi:include href="xml/UDisksFilesystem.xml"/> - <xi:include href="xml/UDisksSwapspace.xml"/> - <xi:include href="xml/UDisksEncrypted.xml"/> - <xi:include href="xml/UDisksLoop.xml"/> - </chapter> - </part> - - <part id="ref-daemon"> - <title>Daemon Implementation Details</title> - <chapter id="ref-daemon-core"> - <title>Core</title> - <xi:include href="xml/udisksdaemonutil.xml"/> - <xi:include href="xml/udiskslogging.xml"/> - <xi:include href="xml/udisksdaemon.xml"/> - <xi:include href="xml/udisksprovider.xml"/> - <xi:include href="xml/udisksstate.xml"/> - <xi:include href="xml/udisksata.xml"/> - </chapter> - <chapter id="ref-daemon-monitoring"> - <title>State and Configuration</title> - <xi:include href="xml/udisksmountmonitor.xml"/> - <xi:include href="xml/udisksfstabmonitor.xml"/> - <xi:include href="xml/udiskscrypttabmonitor.xml"/> - </chapter> - <chapter id="ref-daemon-jobs"> - <title>Jobs</title> - <xi:include href="xml/udisksbasejob.xml"/> - <xi:include href="xml/udiskssimplejob.xml"/> - <xi:include href="xml/udisksthreadedjob.xml"/> - <xi:include href="xml/udisksspawnedjob.xml"/> - </chapter> - <chapter id="ref-daemon-linux-types"> - <title>Linux-specific types</title> - <xi:include href="xml/udiskslinuxmanager.xml"/> - <xi:include href="xml/udiskslinuxprovider.xml"/> - <xi:include href="xml/udiskslinuxdevice.xml"/> - </chapter> - <chapter id="ref-daemon-drives"> - <title>Drives on Linux</title> - <xi:include href="xml/udiskslinuxdrive.xml"/> - <xi:include href="xml/udiskslinuxdriveata.xml"/> - <xi:include href="xml/udiskslinuxdriveobject.xml"/> - </chapter> - <chapter id="ref-daemon-mdraid"> - <title>Linux RAID</title> - <xi:include href="xml/udiskslinuxmdraid.xml"/> - <xi:include href="xml/udiskslinuxmdraidobject.xml"/> - </chapter> - <chapter id="ref-daemon-block-devices"> - <title>Block devices on Linux</title> - <xi:include href="xml/udiskslinuxblock.xml"/> - <xi:include href="xml/udiskslinuxpartition.xml"/> - <xi:include href="xml/udiskslinuxpartitiontable.xml"/> - <xi:include href="xml/udiskslinuxfilesystem.xml"/> - <xi:include href="xml/udiskslinuxencrypted.xml"/> - <xi:include href="xml/udiskslinuxswapspace.xml"/> - <xi:include href="xml/udiskslinuxloop.xml"/> - <xi:include href="xml/udiskslinuxblockobject.xml"/> - </chapter> - </part> - - <index id="api-index"> - <title>Index</title> - </index> - - <index id="api-index-deprecated" role="deprecated"> - <title>Index of deprecated symbols</title> - <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include> - </index> - - <index id="api-index-2.1" role="2.1"> - <title>Index of new symbols in 2.1</title> - <xi:include href="xml/api-index-2.1.xml"><xi:fallback /></xi:include> - </index> - - <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> - - <chapter id="gio-hierarchy"> - <title>Object Hierarchy</title> - <xi:include href="xml/tree_index.sgml"/> - </chapter> -</book> |