doc/xml/gnome-vfs-file-info-ops.xml

   1 <refentry id="gnome-vfs-20-gnome-vfs-file-info-ops">
   2 <refmeta>
   3 <refentrytitle>Getting and Setting File Information</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>GNOME-VFS-2.0 Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Getting and Setting File Information</refname><refpurpose></refpurpose>
  10 </refnamediv>
  11
  12 <refsynopsisdiv><title>Synopsis</title>
  13
  14 <synopsis>
  15
  16
  17
  18 <link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-get-file-info">gnome_vfs_get_file_info</link>      (const <link linkend="gchar">gchar</link> *text_uri,
  19                                              <link linkend="GnomeVFSFileInfo">GnomeVFSFileInfo</link> *info,
  20                                              <link linkend="GnomeVFSFileInfoOptions">GnomeVFSFileInfoOptions</link> options);
  21 <link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-get-file-info-uri">gnome_vfs_get_file_info_uri</link>  (<link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
  22                                              <link linkend="GnomeVFSFileInfo">GnomeVFSFileInfo</link> *info,
  23                                              <link linkend="GnomeVFSFileInfoOptions">GnomeVFSFileInfoOptions</link> options);
  24 <link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-get-file-info-from-handle">gnome_vfs_get_file_info_from_handle</link>
  25                                             (<link linkend="GnomeVFSHandle">GnomeVFSHandle</link> *handle,
  26                                              <link linkend="GnomeVFSFileInfo">GnomeVFSFileInfo</link> *info,
  27                                              <link linkend="GnomeVFSFileInfoOptions">GnomeVFSFileInfoOptions</link> options);
  28 <link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-set-file-info-uri">gnome_vfs_set_file_info_uri</link>  (<link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
  29                                              <link linkend="GnomeVFSFileInfo">GnomeVFSFileInfo</link> *info,
  30                                              <link linkend="GnomeVFSSetFileInfoMask">GnomeVFSSetFileInfoMask</link> mask);
  31 <link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-set-file-info">gnome_vfs_set_file_info</link>      (const <link linkend="gchar">gchar</link> *text_uri,
  32                                              <link linkend="GnomeVFSFileInfo">GnomeVFSFileInfo</link> *info,
  33                                              <link linkend="GnomeVFSSetFileInfoMask">GnomeVFSSetFileInfoMask</link> mask);
  34 </synopsis>
  35 </refsynopsisdiv>
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45 <refsect1>
  46 <title>Description</title>
  47 <para>
  48     Applications can use the <link linkend="gnome-vfs-get-file-info"><type>gnome_vfs_get_file_info</type></link> family of operations to
  49     retrieve file information, as this operation can be quite costly in
  50     terms of time (specilly when sniffing the MIME type) applications can
  51     specify which information need at any time, reducing the performance
  52     impact.
  53 </para>
  54 <para>
  55     All of these operations use a <link linkend="GnomeVFSFileInfo"><type>GnomeVFSFileInfo</type></link> data structure that holds
  56     the file information, there are several methods that can be used to
  57     manipulate this information. See <link linkend="GnomeVFSFileInfo"><type>GnomeVFSFileInfo</type></link> for more information.
  58 </para>
  59 </refsect1>
  60
  61 <refsect1>
  62 <title>Details</title>
  63 <refsect2>
  64 <title><anchor id="gnome-vfs-get-file-info"/>gnome_vfs_get_file_info ()</title>
  65 <indexterm><primary>gnome_vfs_get_file_info</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_get_file_info      (const <link linkend="gchar">gchar</link> *text_uri,
  66                                              <link linkend="GnomeVFSFileInfo">GnomeVFSFileInfo</link> *info,
  67                                              <link linkend="GnomeVFSFileInfoOptions">GnomeVFSFileInfoOptions</link> options);</programlisting>
  68 <para>
  69 Retrieve information about <parameter>text_uri</parameter>.  The information will be stored in
  70 <parameter>info</parameter>.</para>
  71 <para>
  72
  73 </para><variablelist role="params">
  74 <varlistentry><term><parameter>text_uri</parameter>&nbsp;:</term>
  75 <listitem><simpara> URI of the file for which information will be retrieved
  76 </simpara></listitem></varlistentry>
  77 <varlistentry><term><parameter>info</parameter>&nbsp;:</term>
  78 <listitem><simpara> Pointer to a GnomeVFSFileInfo object that will hold the information
  79 for the file on return
  80 </simpara></listitem></varlistentry>
  81 <varlistentry><term><parameter>options</parameter>&nbsp;:</term>
  82 <listitem><simpara> Options for retrieving file information
  83 to retrieve for the file
  84 </simpara></listitem></varlistentry>
  85 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> An integer representing the result of the operation
  86 </simpara></listitem></varlistentry>
  87 </variablelist></refsect2>
  88 <refsect2>
  89 <title><anchor id="gnome-vfs-get-file-info-uri"/>gnome_vfs_get_file_info_uri ()</title>
  90 <indexterm><primary>gnome_vfs_get_file_info_uri</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_get_file_info_uri  (<link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
  91                                              <link linkend="GnomeVFSFileInfo">GnomeVFSFileInfo</link> *info,
  92                                              <link linkend="GnomeVFSFileInfoOptions">GnomeVFSFileInfoOptions</link> options);</programlisting>
  93 <para>
  94 Retrieve information about <parameter>text_uri</parameter>.  The information will be stored in
  95 <parameter>info</parameter>.</para>
  96 <para>
  97
  98 </para><variablelist role="params">
  99 <varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
 100 <listitem><simpara> URI of the file for which information will be retrieved
 101 </simpara></listitem></varlistentry>
 102 <varlistentry><term><parameter>info</parameter>&nbsp;:</term>
 103 <listitem><simpara> Pointer to a GnomeVFSFileInfo object that will hold the information
 104 for the file on return
 105 </simpara></listitem></varlistentry>
 106 <varlistentry><term><parameter>options</parameter>&nbsp;:</term>
 107 <listitem><simpara> Options for retrieving file information
 108 to retrieve for the file
 109 </simpara></listitem></varlistentry>
 110 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> An integer representing the result of the operation
 111 </simpara></listitem></varlistentry>
 112 </variablelist></refsect2>
 113 <refsect2>
 114 <title><anchor id="gnome-vfs-get-file-info-from-handle"/>gnome_vfs_get_file_info_from_handle ()</title>
 115 <indexterm><primary>gnome_vfs_get_file_info_from_handle</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_get_file_info_from_handle
 116                                             (<link linkend="GnomeVFSHandle">GnomeVFSHandle</link> *handle,
 117                                              <link linkend="GnomeVFSFileInfo">GnomeVFSFileInfo</link> *info,
 118                                              <link linkend="GnomeVFSFileInfoOptions">GnomeVFSFileInfoOptions</link> options);</programlisting>
 119 <para>
 120 Retrieve information about an open file.  The information will be stored in
 121 <parameter>info</parameter>.</para>
 122 <para>
 123
 124 </para><variablelist role="params">
 125 <varlistentry><term><parameter>handle</parameter>&nbsp;:</term>
 126 <listitem><simpara> Handle of the file for which information must be retrieved
 127 </simpara></listitem></varlistentry>
 128 <varlistentry><term><parameter>info</parameter>&nbsp;:</term>
 129 <listitem><simpara> Pointer to a GnomeVFSFileInfo object that will hold the information
 130 for the file on return
 131 </simpara></listitem></varlistentry>
 132 <varlistentry><term><parameter>options</parameter>&nbsp;:</term>
 133 <listitem><simpara> Options for retrieving file information
 134 to retrieve for the file
 135 </simpara></listitem></varlistentry>
 136 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> An integer representing the result of the operation
 137 </simpara></listitem></varlistentry>
 138 </variablelist></refsect2>
 139 <refsect2>
 140 <title><anchor id="gnome-vfs-set-file-info-uri"/>gnome_vfs_set_file_info_uri ()</title>
 141 <indexterm><primary>gnome_vfs_set_file_info_uri</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_set_file_info_uri  (<link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
 142                                              <link linkend="GnomeVFSFileInfo">GnomeVFSFileInfo</link> *info,
 143                                              <link linkend="GnomeVFSSetFileInfoMask">GnomeVFSSetFileInfoMask</link> mask);</programlisting>
 144 <para>
 145 Set file information for <parameter>uri</parameter>; only the information for which the
 146 corresponding bit in <parameter>mask</parameter> is set is actually modified.</para>
 147 <para>
 148
 149 </para><variablelist role="params">
 150 <varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
 151 <listitem><simpara> A URI
 152 </simpara></listitem></varlistentry>
 153 <varlistentry><term><parameter>info</parameter>&nbsp;:</term>
 154 <listitem><simpara> Information that must be set for the file
 155 </simpara></listitem></varlistentry>
 156 <varlistentry><term><parameter>mask</parameter>&nbsp;:</term>
 157 <listitem><simpara> Bit mask representing which fields of <parameter>info</parameter> need to be set
 158 </simpara></listitem></varlistentry>
 159 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> An integer representing the result of the operation.
 160 </simpara></listitem></varlistentry>
 161 </variablelist></refsect2>
 162 <refsect2>
 163 <title><anchor id="gnome-vfs-set-file-info"/>gnome_vfs_set_file_info ()</title>
 164 <indexterm><primary>gnome_vfs_set_file_info</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_set_file_info      (const <link linkend="gchar">gchar</link> *text_uri,
 165                                              <link linkend="GnomeVFSFileInfo">GnomeVFSFileInfo</link> *info,
 166                                              <link linkend="GnomeVFSSetFileInfoMask">GnomeVFSSetFileInfoMask</link> mask);</programlisting>
 167 <para>
 168 Set file information for <parameter>uri</parameter>; only the information for which the
 169 corresponding bit in <parameter>mask</parameter> is set is actually modified.</para>
 170 <para>
 171
 172 </para><variablelist role="params">
 173 <varlistentry><term><parameter>text_uri</parameter>&nbsp;:</term>
 174 <listitem><simpara> A URI
 175 </simpara></listitem></varlistentry>
 176 <varlistentry><term><parameter>info</parameter>&nbsp;:</term>
 177 <listitem><simpara> Information that must be set for the file
 178 </simpara></listitem></varlistentry>
 179 <varlistentry><term><parameter>mask</parameter>&nbsp;:</term>
 180 <listitem><simpara> Bit mask representing which fields of <parameter>info</parameter> need to be set
 181 </simpara></listitem></varlistentry>
 182 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> An integer representing the result of the operation.
 183 </simpara></listitem></varlistentry>
 184 </variablelist></refsect2>
 185
 186 </refsect1>
 187
 188
 189
 190 <refsect1>
 191 <title>See Also</title>
 192 <para>
 193
 194 <variablelist>
 195 <varlistentry>
 196 <term><link linkend="GnomeVFSFileInfo"><type>GnomeVFSFileInfo</type></link></term>
 197 </varlistentry>
 198 </variablelist>
 199
 200 </para>
 201 </refsect1>
 202
 203 </refentry>