/ 
Archive-Libarchive-XS-0.0903
River stage zero No dependents
/ Archive::Libarchive::XS::Callback

NAME

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

VERSION

version 0.0903

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.