Difference between revisions of "API:EPrints/DataObj/File"

From EPrints Documentation
Jump to: navigation, search
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- Pod2Wiki=_preamble_  
 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/DataObj/File.pm|package_name=EPrints::DataObj::File}}[[Category:API|FILE]][[Category:API:EPrints/DataObj|FILE]][[Category:API:EPrints/DataObj/File|FILE]]<div><!-- Edit below this comment -->
+
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/DataObj/File.pm|package_name=EPrints::DataObj::File}}[[Category:API|FILE]][[Category:API:EPrints/DataObj|FILE]][[Category:API:EPrints/DataObj/File|FILE]]<div><!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 
==NAME==
 
==NAME==
'''EPrints::DataObj::File''' - a stored file
+
EPrints::DataObj::File - a stored file
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_description -->
 
<!-- Pod2Wiki=head_description -->
 
==DESCRIPTION==
 
==DESCRIPTION==
Line 23: Line 20:
 
This class is a subclass of [[API:EPrints/DataObj/SubObject|EPrints::DataObj::SubObject]].
 
This class is a subclass of [[API:EPrints/DataObj/SubObject|EPrints::DataObj::SubObject]].
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_core_fields -->
 
<!-- Pod2Wiki=head_core_fields -->
 
==CORE FIELDS==
 
==CORE FIELDS==
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
* fileid
<span style='display:none'>User Comments</span>
+
: Unique identifier for this file.
<!-- Edit below this comment -->
 
  
 +
* rev_number (int)
 +
: The number of the current revision of this file.
  
<!-- Pod2Wiki= -->
+
* datasetid
</div>
+
: Id of the dataset of the parent object.
<!-- Pod2Wiki=item_fileid -->
 
===fileid===
 
  
Unique identifier for this file.
+
* objectid
 +
: Id of the parent object.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
* filename
<span style='display:none'>User Comments</span>
+
: Name of the file (may contain directory separators).
<!-- Edit below this comment -->
 
  
 +
* mime_type
 +
: MIME type of the file (e.g. "image/png").
  
<!-- Pod2Wiki= -->
+
* hash
</div>
+
: Check sum of the file.
<!-- Pod2Wiki=item_rev_number -->
 
===rev_number (int)===
 
  
The number of the current revision of this file.
+
* hash_type
 +
: Name of check sum algorithm used (e.g. "MD5").
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
* filesize
<span style='display:none'>User Comments</span>
+
: Size of the file in bytes.
<!-- Edit below this comment -->
 
  
 +
* mtime
 +
: Last modification time of the file.
  
<!-- Pod2Wiki= -->
+
* url
</div>
+
: Virtual field for storing the file's URL.
<!-- Pod2Wiki=item_datasetid -->
 
===datasetid===
 
  
Id of the dataset of the parent object.
+
* data
 +
: Virtual field for storing the file's content.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_methods -->
<!-- Pod2Wiki=item_objectid -->
+
==METHODS==
===objectid===
+
<!-- Pod2Wiki=head_constructor_methods -->
 
+
===Constructor Methods===
Id of the parent object.
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_new_from_filename -->
<!-- Pod2Wiki=item_filename -->
+
===new_from_filename===
===filename===
 
  
Name of the file (may contain directory separators).
+
<source lang="perl">$dataobj = EPrints::DataObj::File->new_from_filename( $session, $dataobj, $filename )
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
</source>
<span style='display:none'>User Comments</span>
+
Convenience method to get an existing File object for $filename stored in $dataobj.
<!-- Edit below this comment -->
 
  
 +
Returns undef if no such record exists.
  
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_mime_type -->
 
===mime_type===
 
 
MIME type of the file (e.g. "image/png").
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_create_from_data -->
<!-- Pod2Wiki=item_hash -->
+
===create_from_data===
===hash===
 
  
Check sum of the file.
+
<source lang="perl">$dataobj = EPrints::DataObj::File->create_from_data( $session, $data [, $dataset ] )
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
</source>
<span style='display:none'>User Comments</span>
+
Create a new File record using $data.
<!-- Edit below this comment -->
 
  
 +
Private data elements:
  
<!-- Pod2Wiki= -->
+
<pre>  _content - content to pass to [[API:EPrints/DataObj/File#set_file|set_file]].
</div>
+
  _filepath - path to source file used for improved mime-type detection</pre>
<!-- Pod2Wiki=item_hash_type -->
 
===hash_type===
 
 
 
Name of check sum algorithm used (e.g. "MD5").
 
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_class_methods -->
<!-- Pod2Wiki=item_filesize -->
+
===Class Methods===
===filesize===
 
 
 
Size of the file in bytes.
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_get_system_field_info -->
<!-- Pod2Wiki=item_mtime -->
+
===get_system_field_info===
===mtime===
 
  
Last modification time of the file.
+
<source lang="perl">$thing = EPrints::DataObj::File->get_system_field_info
 +
 
 +
</source>
 +
Core fields.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_get_dataset_id -->
<!-- Pod2Wiki=item_url -->
+
===get_dataset_id===
===url===
+
 
 +
<source lang="perl">$dataset = EPrints::DataObj::File->get_dataset_id
  
Virtual field for storing the file's URL.
+
</source>
 +
Returns the id of the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record belongs.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_object_methods -->
<!-- Pod2Wiki=item_data -->
+
===Object Methods===
===data===
 
 
 
Virtual field for storing the file's content.
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_clone -->
<!-- Pod2Wiki=head_methods -->
+
===clone===
==METHODS==
+
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
<source lang="perl">$new_file = $file->clone( $parent )
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
  
 +
</source>
 +
Clone the $file object (including contained files) and return the new object.
  
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=head_constructor_methods -->
 
===Constructor Methods===
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_remove -->
<!-- Pod2Wiki=item_new_from_filename -->
+
===remove===
====new_from_filename====
 
  
$dataobj = EPrints::DataObj::File-&gt;new_from_filename( $session, $dataobj, $filename )
+
<source lang="perl">$success = $file->remove
Convenience method to get an existing File object for $filename stored in $dataobj.
 
  
Returns undef if no such record exists.
+
</source>
 +
Delete the stored file.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_update -->
<!-- Pod2Wiki=item_create_from_data -->
+
===update===
====create_from_data====
 
  
$dataobj = EPrints::DataObj::File-&gt;create_from_data( $session, $data [, $dataset ] )
+
<source lang="perl">$file->update( $epdata )
Create a new File record using $data. If "_content" is defined in $data it will be read from and stored - for possible values see set_file().
 
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
</source>
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_get_local_copy -->
<!-- Pod2Wiki=head_class_methods -->
+
===get_local_copy===
===Class Methods===
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
  
 +
<source lang="perl">$filename = $file->get_local_copy()
  
<!-- Pod2Wiki= -->
+
</source>
</div>
+
Return the name of a local copy of the file (may be a {{API:PodLink|file=File/Temp|package_name=File::Temp|section=|text=File::Temp}} object).
<!-- Pod2Wiki=item_get_system_field_info -->
 
====get_system_field_info====
 
  
$thing = EPrints::DataObj::File-&gt;get_system_field_info
+
Will retrieve and cache the remote object if necessary.
Core fields.
 
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_add_file -->
<!-- Pod2Wiki=item_get_dataset_id -->
+
===add_file===
====get_dataset_id====
+
 
 +
<source lang="perl">$success = $file->add_file( $filepath, $filename [, $preserve_path ] )
  
$dataset = EPrints::DataObj::File-&gt;get_dataset_id
+
</source>
Returns the id of the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record belongs.
+
Read and store the contents of $filepath at $filename.
 +
 
 +
If $preserve_path is untrue will strip any leading path in $filename.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_upload -->
<!-- Pod2Wiki=item_get_defaults -->
+
===upload===
====get_defaults====
 
  
$defaults = EPrints::DataObj::File-&gt;get_defaults( $session, $data )
+
<source lang="perl">$bytes = $file->upload( $filehandle, $filename, $filesize [, $preserve_path ] )
Return default values for this object based on the starting data.
 
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
</source>
<span style='display:none'>User Comments</span>
+
Read and store the data from $filehandle at $filename at the next revision number.
<!-- Edit below this comment -->
 
  
 +
If $preserve_path is untrue will strip any leading path in $filename.
 +
 +
Returns the number of bytes read from $filehandle or undef on failure.
  
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=head_object_methods -->
 
===Object Methods===
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_write_copy -->
<!-- Pod2Wiki=item_clone -->
+
===write_copy===
====clone====
 
  
$new_file = $file-&gt;clone( $parent )
+
<source lang="perl">$success = $stored->write_copy( $filename )
Clone the $file object (including contained files) and return the new object.
 
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
</source>
<span style='display:none'>User Comments</span>
+
Write a copy of this file to $filename.
<!-- Edit below this comment -->
 
  
 +
Returns true if the written file contains the same number of bytes as the stored file.
  
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_remove -->
 
====remove====
 
 
$success = $file-&gt;remove
 
Delete the stored file.
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_write_copy_fh -->
<!-- Pod2Wiki=item_get_local_copy -->
+
===write_copy_fh===
====get_local_copy====
 
  
$filename = $file-&gt;get_local_copy()
+
<source lang="perl">$success = $stored->write_copy_fh( $filehandle )
Return the name of a local copy of the file (may be a {{API:PodLink|file=File/Temp|package_name=File::Temp|section=|text=File::Temp}} object).
 
  
Will retrieve and cache the remote object if necessary.
+
</source>
 +
Write a copy of this file to $filehandle.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_generate_md5 -->
<!-- Pod2Wiki=item_add_file -->
+
===generate_md5===
====add_file====
 
  
$success = $file-&gt;add_file( $filepath, $filename [, $preserve_path ] )
+
<source lang="perl">$md5 = $stored->generate_md5
Read and store the contents of $filepath at $filename.
 
  
If $preserve_path is untrue will strip any leading path in $filename.
+
</source>
 +
Calculates and returns the MD5 for this file.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_generate_sha -->
<!-- Pod2Wiki=item_upload -->
+
===generate_sha===
====upload====
 
  
$bytes = $file-&gt;upload( $filehandle, $filename, $filesize [, $preserve_path ] )
+
<source lang="perl">$digest = $file->generate_sha( [ ALGORITHM ] )
Read and store the data from $filehandle at $filename at the next revision number.
 
  
If $preserve_path is untrue will strip any leading path in $filename.
+
</source>
 +
Generate a SHA for this file, see {{API:PodLink|file=Digest/SHA|package_name=Digest::SHA|section=|text=Digest::SHA}} for a list of supported algorithms. Defaults to "256" (SHA-256).
  
Returns the number of bytes read from $filehandle or undef on failure.
+
Returns the hex-encoded digest.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_add_plugin_copy -->
<!-- Pod2Wiki=item_write_copy -->
+
===add_plugin_copy===
====write_copy====
 
  
$success = $stored-&gt;write_copy( $filename )
+
<source lang="perl">$stored->add_plugin_copy( $plugin, $sourceid )
Write a copy of this file to $filename.
 
  
Returns true if the written file contains the same number of bytes as the stored file.
+
</source>
 +
Add a copy of this file stored using $plugin identified by $sourceid.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_remove_plugin_copy -->
<!-- Pod2Wiki=item_write_copy_fh -->
+
===remove_plugin_copy===
====write_copy_fh====
+
 
 +
<source lang="perl">$stored->remove_plugin_copy( $plugin )
  
$success = $stored-&gt;write_copy_fh( $filehandle )
+
</source>
Write a copy of this file to $filehandle.
+
Remove the copy of this file stored using $plugin.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_get_file -->
<!-- Pod2Wiki=item_generate_md5 -->
+
===get_file===
====generate_md5====
 
  
$md5 = $stored-&gt;generate_md5
+
<source lang="perl">$success = $stored->get_file( CALLBACK [, $offset, $n ] )
Calculates and returns the MD5 for this file.
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
  
 +
</source>
 +
Get the contents of the stored file.
  
<!-- Pod2Wiki= -->
+
$offset is the position in bytes to start reading from, defaults to 0.
</div>
 
<!-- Pod2Wiki=item_generate_sha -->
 
====generate_sha====
 
  
$digest = $file-&gt;generate_sha( [ ALGORITHM ] )
+
$n is the number of bytes to read, defaults to <code>filesize</code>.
Generate a SHA for this file, see {{API:PodLink|file=Digest/SHA/PurePerl|package_name=Digest::SHA::PurePerl|section=|text=Digest::SHA::PurePerl}} for a list of supported algorithms. Defaults to "256" (SHA-256).
 
  
Returns the hex-encoded digest.
+
CALLBACK is:
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
<source lang="perl">sub {
<span style='display:none'>User Comments</span>
+
my( $buffer ) = @_;
<!-- Edit below this comment -->
 
  
 +
print $buffer;
  
<!-- Pod2Wiki= -->
+
return 1;
</div>
+
}</source>
<!-- Pod2Wiki=item_add_plugin_copy -->
 
====add_plugin_copy====
 
  
$stored-&gt;add_plugin_copy( $plugin, $sourceid )
+
Returning 0 from the callback will cause the read to abort.
Add a copy of this file stored using $plugin identified by $sourceid.
 
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_set_file -->
<!-- Pod2Wiki=item_remove_plugin_copy -->
+
===set_file===
====remove_plugin_copy====
+
 
 +
<source lang="perl">$content_length = $stored->set_file( CONTENT, $content_length )
 +
 
 +
</source>
 +
Write $content_length bytes from CONTENT to the file object. Updates <code>filesize</code> and <code>hash</code> (you must call [[API:EPrints/DataObj/File#commit|commit]]).
  
$stored-&gt;remove_plugin_copy( $plugin )
+
Returns $content_length or undef on failure.
Remove the copy of this file stored using $plugin.
 
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
If CONTENT has fewer bytes than $content_length the result is undetermined and a warning will be printed.
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
  
 +
CONTENT may be any one of:
  
<!-- Pod2Wiki= -->
+
* CODEREF
</div>
+
: Will be called until it returns empty string ("").
<!-- Pod2Wiki=item_get_file -->
 
====get_file====
 
  
$success = $stored-&gt;get_file( CALLBACK [, $offset, $n ] )
+
<source lang="perl">sub {
Get the contents of the stored file - see [[API:EPrints/Storage#retrieve|EPrints::Storage/retrieve]].
+
sysread($fh, my $buffer, 1024);
 +
return $buffer;
 +
};</source>
  
$offset is the position in bytes to start reading from, default 0.
+
* SCALARREF
 +
: A scalar reference to a string of octets that will be written as-is.
  
$n is the number of bytes to read, default <tt>filesize</tt>.
+
* GLOB
 +
: Will be treated as a file handle and read with sysread() until the eof.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_set_file_chunk -->
<!-- Pod2Wiki=item_set_file -->
+
===set_file_chunk===
====set_file====
 
  
$content_length = $stored-&gt;set_file( CONTENT, $content_length )
+
<source lang="perl">$content_length = $file->set_file_chunk( CONTENT, $content_length, $offset, $total )
Reads data from CONTENT and stores it. Sets the MD5 hash and filesize.
 
  
If the write failed returns undef and sets the filesize to 0.
+
</source>
 +
Write a chunk of data to the content, overwriting or appending to the existing content. See [[API:EPrints/DataObj/File#set_file|set_file]] for CONTENT and $content_length. <code>filesize</code> is updated if $offset + $content_length is greater than the current <code>filesize</code>.
  
CONTENT may be one of:
+
$offset is the starting point (in bytes) to write. $total is the total file size, used to determine where to store the content.
  
  CODEREF - will be called until it returns empty string ("")
+
Returns the number of bytes written or undef on failure.
  SCALARREF - a scalar reference will be used as-is (expects bytes)
 
  GLOB - will be treated as a file handle and read with sysread()
 
 
 
This method does not check the actual number of bytes read is the same as $content_length.
 
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_see_also -->
 
<!-- Pod2Wiki=head_see_also -->
 
==SEE ALSO==
 
==SEE ALSO==
 +
[[API:EPrints/Storage|EPrints::Storage]]
 +
 
[[API:EPrints/DataObj|EPrints::DataObj]] and [[API:EPrints/DataSet|EPrints::DataSet]].
 
[[API:EPrints/DataObj|EPrints::DataObj]] and [[API:EPrints/DataSet|EPrints::DataSet]].
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_copyright -->
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->
+
==COPYRIGHT==
 +
Copyright 2000-2013 University of Southampton.
 +
 
 +
This file is part of EPrints http://www.eprints.org/.
 +
 
 +
EPrints 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 3 of the License, or (at your option) any later version.
 +
 
 +
EPrints 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 EPrints.  If not, see http://www.gnu.org/licenses/.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=_postamble_ -->
 +
<!-- Edit below this comment -->

Revision as of 13:36, 25 July 2013

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects


API: Core API

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki


NAME

EPrints::DataObj::File - a stored file


DESCRIPTION

This class contains the technical metadata associated with a file. A file is a sequence of bytes stored in the storage layer (a "stored object"). Utility methods for storing and retrieving the stored object from the storage layer are made available.

Revision numbers on File work slightly differently to other objects. A File is only revised when it's stored object is changed and not when changes to it's metadata are made.

This class is a subclass of EPrints::DataObj::SubObject.


CORE FIELDS

  • fileid
Unique identifier for this file.
  • rev_number (int)
The number of the current revision of this file.
  • datasetid
Id of the dataset of the parent object.
  • objectid
Id of the parent object.
  • filename
Name of the file (may contain directory separators).
  • mime_type
MIME type of the file (e.g. "image/png").
  • hash
Check sum of the file.
  • hash_type
Name of check sum algorithm used (e.g. "MD5").
  • filesize
Size of the file in bytes.
  • mtime
Last modification time of the file.
  • url
Virtual field for storing the file's URL.
  • data
Virtual field for storing the file's content.


METHODS

Constructor Methods

new_from_filename

$dataobj = EPrints::DataObj::File->new_from_filename( $session, $dataobj, $filename )

Convenience method to get an existing File object for $filename stored in $dataobj.

Returns undef if no such record exists.


create_from_data

$dataobj = EPrints::DataObj::File->create_from_data( $session, $data [, $dataset ] )

Create a new File record using $data.

Private data elements:

  _content - content to pass to [[API:EPrints/DataObj/File#set_file|set_file]].
  _filepath - path to source file used for improved mime-type detection


Class Methods

get_system_field_info

$thing = EPrints::DataObj::File->get_system_field_info

Core fields.


get_dataset_id

$dataset = EPrints::DataObj::File->get_dataset_id

Returns the id of the EPrints::DataSet object to which this record belongs.


Object Methods

clone

$new_file = $file->clone( $parent )

Clone the $file object (including contained files) and return the new object.


remove

$success = $file->remove

Delete the stored file.


update

$file->update( $epdata )


get_local_copy

$filename = $file->get_local_copy()

Return the name of a local copy of the file (may be a File::Temp object).

Will retrieve and cache the remote object if necessary.


add_file

$success = $file->add_file( $filepath, $filename [, $preserve_path ] )

Read and store the contents of $filepath at $filename.

If $preserve_path is untrue will strip any leading path in $filename.


upload

$bytes = $file->upload( $filehandle, $filename, $filesize [, $preserve_path ] )

Read and store the data from $filehandle at $filename at the next revision number.

If $preserve_path is untrue will strip any leading path in $filename.

Returns the number of bytes read from $filehandle or undef on failure.


write_copy

$success = $stored->write_copy( $filename )

Write a copy of this file to $filename.

Returns true if the written file contains the same number of bytes as the stored file.


write_copy_fh

$success = $stored->write_copy_fh( $filehandle )

Write a copy of this file to $filehandle.


generate_md5

$md5 = $stored->generate_md5

Calculates and returns the MD5 for this file.


generate_sha

$digest = $file->generate_sha( [ ALGORITHM ] )

Generate a SHA for this file, see Digest::SHA for a list of supported algorithms. Defaults to "256" (SHA-256).

Returns the hex-encoded digest.


add_plugin_copy

$stored->add_plugin_copy( $plugin, $sourceid )

Add a copy of this file stored using $plugin identified by $sourceid.


remove_plugin_copy

$stored->remove_plugin_copy( $plugin )

Remove the copy of this file stored using $plugin.


get_file

$success = $stored->get_file( CALLBACK [, $offset, $n ] )

Get the contents of the stored file.

$offset is the position in bytes to start reading from, defaults to 0.

$n is the number of bytes to read, defaults to filesize.

CALLBACK is:

sub {
	my( $buffer ) = @_;

	print $buffer;

	return 1;
}

Returning 0 from the callback will cause the read to abort.


set_file

$content_length = $stored->set_file( CONTENT, $content_length )

Write $content_length bytes from CONTENT to the file object. Updates filesize and hash (you must call commit).

Returns $content_length or undef on failure.

If CONTENT has fewer bytes than $content_length the result is undetermined and a warning will be printed.

CONTENT may be any one of:

  • CODEREF
Will be called until it returns empty string ("").
sub {
	sysread($fh, my $buffer, 1024);
	return $buffer;
};
  • SCALARREF
A scalar reference to a string of octets that will be written as-is.
  • GLOB
Will be treated as a file handle and read with sysread() until the eof.


set_file_chunk

$content_length = $file->set_file_chunk( CONTENT, $content_length, $offset, $total )

Write a chunk of data to the content, overwriting or appending to the existing content. See set_file for CONTENT and $content_length. filesize is updated if $offset + $content_length is greater than the current filesize.

$offset is the starting point (in bytes) to write. $total is the total file size, used to determine where to store the content.

Returns the number of bytes written or undef on failure.


SEE ALSO

EPrints::Storage

EPrints::DataObj and EPrints::DataSet.


COPYRIGHT

Copyright 2000-2013 University of Southampton.

This file is part of EPrints http://www.eprints.org/.

EPrints 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 3 of the License, or (at your option) any later version.

EPrints 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 EPrints. If not, see http://www.gnu.org/licenses/.