<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-matevfs-handle">
  <refnamediv>
    <refname>matevfs.Handle</refname>
    <refpurpose>Object representing an open file</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>
    <classsynopsis language="python">
      <ooclass><classname>matevfs.Handle</classname></ooclass>
      <constructorsynopsis language="python">
        <methodname><link linkend="constructor-matevfs-handle">matevfs.Handle</link></methodname>
	<methodparam><parameter role="keyword">uri</parameter></methodparam>
	<methodparam><parameter role="keyword">open_mode</parameter><initializer>matevfs.OPEN_READ</initializer></methodparam>
      </constructorsynopsis>
      <methodsynopsis>
        <methodname><link linkend="method-matevfs-handle--close">close</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis>
        <methodname><link linkend="method-matevfs-handle--get_file_info">get_file_info</link></methodname>
	<methodparam><parameter role="keyword">options</parameter><initializer>matevfs.FILE_INFO_DEFAULT</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis>
        <methodname><link linkend="method-matevfs-handle--read">read</link></methodname>
	<methodparam><parameter role="keyword">bytes</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis>
        <methodname><link linkend="method-matevfs-handle--seek">seek</link></methodname>
	<methodparam><parameter role="keyword">offset</parameter></methodparam>
	<methodparam><parameter role="keyword">whence</parameter><initializer>matevfs.SEEK_START</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis>
        <methodname><link linkend="method-matevfs-handle--tell">tell</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis>
        <methodname><link linkend="method-matevfs-handle--truncate">truncate</link></methodname>
	<methodparam><parameter role="keyword">length</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis>
        <methodname><link linkend="method-matevfs-handle--write">write</link></methodname>
	<methodparam><parameter role="keyword">buffer</parameter></methodparam>
      </methodsynopsis>
    </classsynopsis>
  </refsect1>

  <refsect1>
    <title>Description</title>
    <para></para>
  </refsect1>

  <refsect1>
    <title>Constructor</title>

    <refsect2 id="constructor-matevfs-handle">
      <programlisting>
        <constructorsynopsis language="python">
          <methodname><link linkend="constructor-matevfs-handle">matevfs.Handle</link></methodname>
	  <methodparam><parameter role="keyword">uri</parameter></methodparam>
	  <methodparam><parameter role="keyword">open_mode</parameter><initializer>matevfs.OPEN_READ</initializer></methodparam>
        </constructorsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
	  <term><parameter role="keyword">uri</parameter>:</term>
	  <listitem><simpara>The URI to open.</simpara></listitem>
	</varlistentry>
        <varlistentry>
	  <term><parameter role="keyword">open_mode</parameter>:</term>
	  <listitem><simpara>Or'd set of <link linkend="matevfs-constants-openmode">open mode flags</link></simpara></listitem>
	</varlistentry>
        <varlistentry>
	  <term><emphasis>Returns</emphasis>:</term>
	  <listitem><simpara>the new <link linkend="class-matevfs-handle"><classname>matevfs.Handle</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>
      <para></para>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-matevfs-handle--close">
      <title>matevfs.Handle.close</title>
      <programlisting>
        <methodsynopsis language="python">
          <methodname>close</methodname>
	  <methodparam></methodparam>
        </methodsynopsis>
      </programlisting>
      <para>Close the file associated with this handle.</para>
    </refsect2>

    <refsect2 id="method-matevfs-handle--get_file_info">
      <title>matevfs.Handle.get_file_info</title>
      <programlisting>
        <methodsynopsis language="python">
          <methodname>get_file_info</methodname>
	  <methodparam><parameter role="keyword">options</parameter><initializer>matevfs.FILE_INFO_DEFAULT</initializer></methodparam>
        </methodsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
	  <term><parameter role="keyword">options</parameter>:</term>
	  <listitem><simpara>Or'd set of <link linkend="matevfs-constants-fileinfo-options">file info options</link></simpara></listitem>
	</varlistentry>
        <varlistentry>
	  <term><emphasis>Returns</emphasis>:</term>
	  <listitem><simpara>A <link linkend="class-matevfs-fileinfo">matevfs.FileInfo</link>.</simpara></listitem>
	</varlistentry>
      </variablelist>
      <para>Get information about the file, persuant to the options given.</para>
    </refsect2>

    <refsect2 id="method-matevfs-handle--read">
      <title>matevfs.Handle.read</title>
      <programlisting>
        <methodsynopsis language="python">
          <methodname>read</methodname>
	  <methodparam><parameter role="keyword">bytes</parameter></methodparam>
        </methodsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
	  <term><parameter role="keyword">bytes</parameter>:</term>
	  <listitem><simpara>The number of bytes to read</simpara></listitem>
	</varlistentry>
        <varlistentry>
	  <term><emphasis>Returns</emphasis>:</term>
	  <listitem><simpara>A string containing the data.</simpara></listitem>
	</varlistentry>
      </variablelist>
      <para>Read <parameter role="keyword">bytes</parameter> from file.  The actual number of bytes read may be less than this, so you may need to check the length of the string returned.</para>
    </refsect2>

    <refsect2 id="method-matevfs-handle--seek">
      <title>matevfs.Handle.seek</title>
      <programlisting>
        <methodsynopsis language="python">
          <methodname>seek</methodname>
	  <methodparam><parameter role="keyword">offset</parameter></methodparam>
	  <methodparam><parameter role="keyword">whence</parameter><initializer>matevfs.SEEK_START</initializer></methodparam>
        </methodsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
	  <term><parameter role="keyword">offset</parameter>:</term>
	  <listitem><simpara>The number of bytes to offset from the position specified by <parameter role="keyword">whence</parameter>.  This can be either positive or negative.</simpara></listitem>
	</varlistentry>
        <varlistentry>
	  <term><parameter role="keyword">whence</parameter>:</term>
	  <listitem><simpara>The <link linkend="matevfs-constants-seekmode">start position</link>.</simpara></listitem>
	</varlistentry>
      </variablelist>
      <para>Set the current position for reading/writing.</para>
    </refsect2>

    <refsect2 id="method-matevfs-handle--tell">
      <title>matevfs.Handle.tell</title>
      <programlisting>
        <methodsynopsis language="python">
          <methodname>tell</methodname>
	  <methodparam></methodparam>
        </methodsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
	  <term><emphasis>Returns</emphasis>:</term>
	  <listitem><simpara>A long specifying the current byte position.</simpara></listitem>
	</varlistentry>
      </variablelist>
      <para>Returns the current position in the file.  This is the position at which any reads or writes will begin at.</para>
    </refsect2>

    <refsect2 id="method-matevfs-handle--truncate">
      <title>matevfs.Handle.truncate</title>
      <programlisting>
        <methodsynopsis language="python">
          <methodname>truncate</methodname>
	  <methodparam><parameter role="keyword">length</parameter></methodparam>
        </methodsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
	  <term><parameter role="keyword">length</parameter>:</term>
	  <listitem><simpara>The length to truncate to.</simpara></listitem>
	</varlistentry>
      </variablelist>
      <para>Truncates the file to the length specified.</para>
    </refsect2>

    <refsect2 id="method-matevfs-handle--write">
      <title>matevfs.Handle.write</title>
      <programlisting>
        <methodsynopsis language="python">
          <methodname>write</methodname>
	  <methodparam><parameter role="keyword">buffer</parameter></methodparam>
        </methodsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
	  <term><parameter role="keyword">buffer</parameter>:</term>
	  <listitem><simpara>The buffer to write to the file.</simpara></listitem>
	</varlistentry>
        <varlistentry>
	  <term><emphasis>Returns</emphasis>:</term>
	  <listitem><simpara>The number of bytes written.</simpara></listitem>
	</varlistentry>
      </variablelist>
      <para>Write <parameter role="keyword">buffer</parameter> to the file.  The number of bytes actually written may be less than the buffer, as is provided as the return value.</para>
    </refsect2>
  </refsect1>
</refentry>
