Editing API:EPrints/Storage (section)

==METHODS==
<!-- Pod2Wiki=head_new -->
===new===

<source lang="perl">$store = EPrints::Storage->new( $repository )

</source>
Create a new storage object for $repository. Should not be used directly, see [[API:EPrints/Session|EPrints::Session]].

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_store -->
===store===

<source lang="perl">$len = $store->store( $fileobj, CODEREF [, $offset ] )

</source>
Read from and store all data from CODEREF for $fileobj. If $offset is given starts writing from that point onwards.

Behaviour is undefined if an attempt is made to write beyond $fileobj's '''filesize'''.

Returns the number of bytes written or undef if an error occurred.

<!-- Edit below this comment -->

The combination of methods open_write, write, and close_write can be used as an alternative to this method.
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_retrieve -->
===retrieve===

<source lang="perl">$success = $store->retrieve( $fileobj, $offset, $n, CALLBACK )

</source>
Retrieve the contents of the $fileobj starting at $offset for $n bytes.

CALLBACK = $rc = &amp;f( BUFFER )

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_delete -->
===delete===

<source lang="perl">$success = $store->delete( $fileobj )

</source>
Delete all object copies stored for $fileobj.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_delete_copy -->
===delete_copy===

<source lang="perl">$ok = $store->delete_copy( $plugin, $fileobj )

</source>
Delete the copy of this file stored in the storage layer [[API:EPrints/Plugin/Storage|$plugin]].

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_get_local_copy -->
===get_local_copy===

<source lang="perl">$fh = $store->get_local_copy( $fileobj )

</source>
Return a local copy of the file. Potentially expensive if the file has to be retrieved.

Stringifying $fh will give the full path to the local file, which may be useful for calling external tools (see {{API:PodLink|file=File/Temp|package_name=File::Temp|section=|text=File::Temp}}).

Returns undef if retrieval failed.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_get_remote_copy -->
===get_remote_copy===

<source lang="perl">$url = $store->get_remote_copy( $fileobj )

</source>
Some storage back-ends may provide direct Web access to the data stream (e.g. Amazon S3). If the back-end supports this, a user can be redirected to the storage back-end rather than downloading the file from EPrints. Internally, EPrints will always use the [[API:EPrints/Storage#retrieve|retrieve]] method.

Returns a URL from which this file can be accessed.

Returns undef if this file is not available via another service.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_get_plugins -->
===get_plugins===

<source lang="perl">@plugins = $store->get_plugins( $fileobj )

</source>
Returns the [[API:EPrints/Plugin/Storage|EPrints::Plugin::Storage]] plugin(s) available to use for $fileobj, based on the storage policy. If more than one plugin is returned they should be used in turn until one succeeds.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_copy -->
===copy===

<source lang="perl">$ok = $store->copy( $plugin, $fileobj )

</source>
Copy the contents of $fileobj into another storage $plugin. This uses [[API:EPrints/Storage#retrieve|retrieve]] and [[API:EPrints/Storage#store|store]].

Returns 1 on success, 0 on failure and -1 if a copy already exists in $plugin.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_open_write -->
===open_write===

<source lang="perl">$ok = $storage->open_write( $fileobj [, $offset ] )

</source>
Start a write session for $fileobj. $fileobj must have at least the "filesize" property set (which is the total number of bytes that will be written).

Don't forget to [[API:EPrints/Storage#close_write|close_write]] otherwise the handle to the write will be left open.

<!-- Edit below this comment -->

This, along with write and close_write, is an alternative to the store method.
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_write -->
===write===

<source lang="perl">$ok = $storage->write( $fileobj, $buffer )

</source>
Write $buffer to the storage plugin(s), starting from the previously written data.

<!-- Edit below this comment -->

This, along with open_write and close_write, is an alternative to the store method.
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_close_write -->
===close_write===

<source lang="perl">$ok = $storage->close_write( $fileobj );

</source>
Finish writing to the storage plugin(s) for $fileobj.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_copyright -->