NAME
zip_source_function,
  
zip_source_function_create — 
create
  data source from function
LIBRARY
libzip (-lzip)
SYNOPSIS
#include <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, andZIP_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, andZIP_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, andZIP_SOURCE_REMOVE.
ZIP_SOURCE_BEGIN_WRITE
Prepare the source for writing. Use this to create any temporary file(s).
ZIP_SOURCE_BEGIN_WRITE_CLONING
Prepare the source for writing, keeping the first 
len
  bytes of the original file. Only implement this command if it is more
  efficient than copying the data, and if it does not destructively overwrite
  the original file (you still have to be able to execute
  
ZIP_SOURCE_ROLLBACK_WRITE).
The next write should happen at byte 
offset.
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 
userdata. 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, and zero for end-of-file.
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.
For uncompressed, unencrypted data, all information is optional. However, fill
  in as much information as is readily available.
If the data is compressed, 
ZIP_STAT_COMP_METHOD,
  
ZIP_STAT_SIZE, and
  
ZIP_STAT_CRC must be filled in.
If the data is encrypted, 
ZIP_STAT_ENCRYPTION_METHOD,
  
ZIP_STAT_COMP_METHOD,
  
ZIP_STAT_SIZE, and
  
ZIP_STAT_CRC must be filled in.
Information only available after the source has been read (e.g., size) can be
  omitted in an earlier call. 
NOTE:
  
zip_source_function() may be called with this argument even
  after being called with 
ZIP_SOURCE_CLOSE.
Return sizeof(struct zip_stat) on success.
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 or
  
ZIP_SOURCE_BEGIN_WRITE_CLONING 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 or
  
ZIP_SOURCE_BEGIN_WRITE_CLONING 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)
HISTORY
zip_source_function() and
  
zip_source_function_create() were added in libzip 1.0.
AUTHORS
Dieter Baron
  <
dillo@nih.at> and
  
Thomas Klausner
  <
tk@giga.or.at>