DragonFly On-Line Manual Pages
ZIP_SOURCE_FUNCTION(3) Library Functions Manual ZIP_SOURCE_FUNCTION(3)
NAME
zip_source_function - create data source from function
LIBRARY
libzip (-lzip)
SYNOPSIS
zip.h zip_source_t * zip_source_function zip_t *archive
zip_source_callback fn void *userdata zip_source_t *
zip_source_function_create zip_source_callback fn void *userdata
zip_error_t *error
DESCRIPTION
The functions zip_source_function and zip_source_function_create
creates a zip source from the user-provided function fn, which must be
of the following type:
typedef zip_int64_t (*zip_source_callback) void *userdata void *data
zip_uint64_t len zip_source_cmd_t cmd
archive or error are used for reporting errors and can be NULL.
When called by the library, the first argument is the userdata argument
supplied to the function. The next two arguments are a buffer data of
size len when data is passed in or expected to be returned, or else
NULL and 0. The last argument, cmd, specifies which action the
function should perform.
Depending on the uses, there are three useful sets of commands to be
supported by a zip_source_callback:
read source
Providing streamed data (for file data added to archives). Must
support ZIP_SOURCE_OPEN, ZIP_SOURCE_READ, ZIP_SOURCE_CLOSE,
ZIP_SOURCE_STAT, and ZIP_SOURCE_ERROR.
seekable read source
Same as previous, but from a source allowing reading from
arbitrary offsets (also for read-only zip archive). Must
additionally support ZIP_SOURCE_SEEK, ZIP_SOURCE_TELL, and
ZIP_SOURCE_SUPPORTS.
read/write source
Same as previous, but additionally allowing writing (also for
writable zip archives). Must additionally support
ZIP_SOURCE_BEGIN_WRITE, ZIP_SOURCE_COMMIT_WRITE,
ZIP_SOURCE_ROLLBACK_WRITE, ZIP_SOURCE_SEEK_WRITE,
ZIP_SOURCE_TELL_WRITE, and ZIP_SOURCE_REMOVE.
ZIP_SOURCE_BEGIN_WRITE
Prepare the source for writing. Use this to create any temporary
file(s).
ZIP_SOURCE_CLOSE
Reading is done.
ZIP_SOURCE_COMMIT_WRITE
Finish writing to the source. Replace the original data with the newly
written data. Clean up temporary files or internal buffers.
Subsequently opening and reading from the source should return the
newly written data.
ZIP_SOURCE_ERROR
Get error information. data points to an array of two ints, which
should be filled with the libzip error code and the corresponding
system error code for the error that occurred. See zip_errors(3) for
details on the error codes. If the source stores error information in
a zip_error_t, use zip_error_to_data(3) and return its return value.
Otherwise, return 2 * sizeof(int).
ZIP_SOURCE_FREE
Clean up and free all resources, including state. The callback
function will not be called again.
ZIP_SOURCE_OPEN
Prepare for reading.
ZIP_SOURCE_READ
Read data into the buffer data of size len. Return the number of bytes
placed into data on success.
ZIP_SOURCE_REMOVE
Remove the underlying file. This is called if a zip archive is empty
when closed.
ZIP_SOURCE_ROLLBACK_WRITE
Abort writing to the source. Discard written data. Clean up temporary
files or internal buffers. Subsequently opening and reading from the
source should return the original data.
ZIP_SOURCE_SEEK
Specify position to read next byte from, like fseek(3). Use
ZIP_SOURCE_GET_ARGS(3) to decode the arguments into the following
struct:
struct zip_source_args_seek {
zip_int64_t offset;
int whence;
};
If the size of the source's data is known, use
zip_source_seek_compute_offset(3) to validate the arguments and compute
the new offset.
ZIP_SOURCE_SEEK_WRITE
Specify position to write next byte to, like fseek(3). See
ZIP_SOURCE_SEEK for details.
ZIP_SOURCE_STAT
Get meta information for the input data. data points to an allocated
struct zip_stat, which should be initialized using zip_stat_init(3) and
then filled in. Information only available after the source has been
read (e.g. size) can be omitted in an earlier call. Return
sizeof(struct zip_stat) on success. NOTE: zip_source_function may be
called with this argument even after being called with
ZIP_SOURCE_CLOSE.
ZIP_SOURCE_SUPPORTS
Return bitmap specifying which commands are supported. Use
zip_source_make_command_bitmap(3). If this command is not implemented,
the source is assumed to be a read source without seek support.
ZIP_SOURCE_TELL
Return the current read offset in the source, like ftell(3).
ZIP_SOURCE_TELL_WRITE
Return the current write offset in the source, like ftell(3).
ZIP_SOURCE_WRITE
Write data to the source. Return number of bytes written.
Return Values
Commands should return -1 on error. ZIP_SOURCE_ERROR will be called to
retrieve the error code. On success, commands return 0, unless
specified otherwise in the description above.
Calling Conventions
The library will always issue ZIP_SOURCE_OPEN before issuing
ZIP_SOURCE_READ, ZIP_SOURCE_SEEK, or ZIP_SOURCE_TELL. When it no
longer wishes to read from this source, it will issue ZIP_SOURCE_CLOSE.
If the library wishes to read the data again, it will issue
ZIP_SOURCE_OPEN a second time. If the function is unable to provide
the data again, it should return -1.
ZIP_SOURCE_BEGIN_WRITE will be called before ZIP_SOURCE_WRITE,
ZIP_SOURCE_SEEK_WRITE, or ZIP_SOURCE_TELL_WRITE. When writing is
complete, either ZIP_SOURCE_COMMIT_WRITE or ZIP_SOURCE_ROLLBACK_WRITE
will be called.
ZIP_SOURCE_STAT can be issued at any time.
ZIP_SOURCE_ERROR will only be issued in response to the function
returning -1.
ZIP_SOURCE_FREE will be the last command issued; if ZIP_SOURCE_OPEN was
called and succeeded, ZIP_SOURCE_CLOSE will be called before
ZIP_SOURCE_FREE, and similarly for ZIP_SOURCE_BEGIN_WRITE and
ZIP_SOURCE_COMMIT_WRITE or ZIP_SOURCE_ROLLBACK_WRITE.
RETURN VALUES
Upon successful completion, the created source is returned. Otherwise,
NULL is returned and the error code in archive or error is set to
indicate the error (unless it is NULL).
ERRORS
zip_source_function fails if:
[ZIP_ER_MEMORY] Required memory could not be allocated.
SEE ALSO
libzip(3), zip_add(3), zip_replace(3), zip_source(3), zip_stat_init(3)
AUTHORS
Dieter Baron <dillo@nih.at> and Thomas Klausner <tk@giga.or.at>
NiH November 13, 2014 ZIP_SOURCE_FUNCTION(3)