NAME

Archive::Libarchive::XS::Callback - libarchive callback functions

VERSION

version 0.0900

SYNOPSIS

 use Archive::Libarchive::XS qw( :all );
 
 # read
 my $archive = archive_read_new();
 archive_read_open($archive, $data, \&myopen, \&myread, \&myclose);
 
 # write
 my $archive = archive_write_new();
 archive_write_open($archive, $data, \&myopen, \&mywrite, \&myclose);

DESCRIPTION

This document provides information of callback routines for writing custom input/output interfaces to the libarchive perl bindings. The first two arguments passed into all callbacks are:

$archive

The archive object (actually a pointer to the C structure that managed the archive object).

$data

The callback data object (any legal Perl data structure).

For the variable name / types conventions used in this document, see Archive::Libarchive::XS::Function.

The expected return value for all callbacks EXCEPT the read callback is a standard integer libarchive status value (example: ARCHIVE_OK or ARCHIVE_FATAL).

If your callback dies (throws an exception), it will be caught at the Perl level. The error will be sent to standard error via warn and ARCHIVE_FATAL will be passed back to libarchive.

data

There is a data field for callbacks associated with each $archive object. It can be any native Perl type (example: scalar, hashref, coderef, etc). You can set this by calling archive_read_set_callback_data, or by passing the data argument when you "open" the archive using archive_read_open, archive_read_open2 or archive_write_open.

The data field will be passed into each callback as its second argument.

open

 my $status1 = archive_read_set_open_callback($archive, sub {
   my($archive, $data) = @_;
   ...
   return $status2;
 });

According to the libarchive, this is never needed, but you can register a callback to happen when you open.

Can also be set when you call archive_read_open, archive_read_open2 or archive_write_open.

read

 my $status1 = archive_read_set_read_callback($archive, sub {
   my($archive, $data) = @_;
   ...
   return ($status2, $buffer)
 });

This callback is called whenever libarchive is ready for more data to process. It doesn't take in any additional arguments, but it expects two return values, a status and a buffer containing the data.

Can also be set when you call archive_read_open or archive_read_open2.

write

 my $mywrite = sub {
   my($archive, $data, $buffer) = @_;
   ...
   return $bytes_written_or_status;
 };
 my $status2 = archive_write_open($archive, undef, $mywrite, undef);

This callback is called whenever libarchive has data it wants to send to output. The callback itself takes one additional argument, a buffer containing the data to write.

It should return the actual number of bytes written by you, or an status value for an error.

skip

 my $status1 = archive_read_set_skip_callback($archive, sub {
   my($archive, $data, $request) = @_;
   ...
   return $status2;
 });

The skip callback takes one additional argument, $request.

Can also be set when you call archive_read_open2.

seek

 my $status1 = archive_read_set_seek_callback($archive, sub {
   my($archive, $data, $offset, $whence) = @_;
   ...
   return $status2;
 });

The seek callback should implement an interface identical to the UNIX fseek function.

close

 my $status1 = archive_read_set_close_callback($archive, sub {
   my($archive, $data) = @_;
   ...
   return $status2;
 });

Called when the archive (either input or output) should be closed.

Can also be set when you call archive_read_open, archive_read_open2 or archive_write_open.

user id lookup

 my $status = archive_write_disk_set_user_lookup($archive, $data, sub {
   my($data, $name, $uid) = @_;
   ... # should return the UID for $name or $uid if it can't be found
 }, undef);

Called by archive_write_disk_uid to determine appropriate UID.

group id lookup

 my $status = archive_write_disk_set_group_lookup($archive, $data, sub {
   my($data, $name, $gid) = @_;
   ... # should return the GID for $name or $gid if it can't be found
 }, undef);

Called by archive_write_disk_gid to determine appropriate GID.

user name lookup

 my $status = archive_read_disk_set_uname_lookup($archive, $data, sub 
   my($data, $uid) = @_;
   ... # should return the name for $uid, or undef
 }, undef);

Called by archive_read_disk_uname to determine appropriate user name.

group name lookup

 my $status = archive_read_disk_set_gname_lookup($archive, $data, sub 
   my($data, $gid) = @_;
   ... # should return the name for $gid, or undef
 }, undef);

Called by archive_read_disk_gname to determine appropriate group name.

lookup cleanup

 sub mycleanup
 {
   my($data) = @_;
   ... # any cleanup necessary
 }
 
 my $status = archive_write_disk_set_user_lookup($archive, $data, \&mylookup, \&mcleanup);
 
 ...
 
 archive_write_disk_set_user_lookup($archive, undef, undef, undef); # mycleanup will be called here

Called when the lookup is registered (can also be passed into archive_write_disk_set_group_lookup, archive_read_disk_set_uname_lookup, and archive_read_disk_set_gname_lookup.

SEE ALSO

Archive::Libarchive::XS

Archive::Libarchive::XS::Constant

Archive::Libarchive::XS::Function

AUTHOR

Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Archive::Libarchive::XS

perl -MCPAN -e shell
install Archive::Libarchive::XS