| ZIP_SOURCE_FUNCTION(3) | Library Functions Manual | ZIP_SOURCE_FUNCTION(3) |
zip_source_function,
zip_source_function_create —
#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);
zip_source_function() and
zip_source_function_create() create 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():
ZIP_SOURCE_OPEN,
ZIP_SOURCE_READ,
ZIP_SOURCE_CLOSE,
ZIP_SOURCE_STAT, and
ZIP_SOURCE_ERROR.
If your source uses any allocated memory (including
userdata) it should also implement
ZIP_SOURCE_FREE to avoid memory leaks.
ZIP_SOURCE_SEEK,
ZIP_SOURCE_TELL, and
ZIP_SOURCE_SUPPORTS.ZIP_SOURCE_BEGIN_WRITE,
ZIP_SOURCE_COMMIT_WRITE,
ZIP_SOURCE_ROLLBACK_WRITE,
ZIP_SOURCE_SEEK_WRITE,
ZIP_SOURCE_TELL_WRITE, and
ZIP_SOURCE_REMOVE.
On top of the above, supporting the pseudo-command
ZIP_SOURCE_SUPPORTS_REOPEN allows calling
zip_source_open() again after calling
zip_source_close().
ZIP_SOURCE_ACCEPT_EMPTYZIP_SOURCE_BEGIN_WRITEZIP_SOURCE_BEGIN_WRITE_CLONINGZIP_SOURCE_ROLLBACK_WRITE).
The next write should happen at byte offset.
ZIP_SOURCE_CLOSEZIP_SOURCE_COMMIT_WRITEZIP_SOURCE_ERRORZIP_SOURCE_FREEZIP_SOURCE_GET_FILE_ATTRIBUTESZIP_FILE_ATTRIBUTES_*
value must be or'ed into the valid member to denote that
the corresponding data has been provided. A
zip_file_attributes_t structure can be initialized using
zip_file_attributes_init(3).
ZIP_FILE_ATTRIBUTES_ASCII.ZIP_FILE_ATTRIBUTES_GENERAL_PURPOSE_BIT_FLAGS.ZIP_FILE_ATTRIBUTES_EXTERNAL_FILE_ATTRIBUTES.ZIP_FILE_ATTRIBUTES_VERSION_NEEDED.ZIP_OPSYS_* variables (see
zip.h). This value affects the interpretation of
the external file attributes. Member host_system,
flag ZIP_FILE_ATTRIBUTES_HOST_SYSTEM.ZIP_SOURCE_OPENZIP_SOURCE_READZIP_SOURCE_REMOVEZIP_SOURCE_ROLLBACK_WRITEZIP_SOURCE_SEEK
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_WRITEZIP_SOURCE_SEEK for details.
ZIP_SOURCE_STATFor 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_SUPPORTSZIP_SOURCE_TELLZIP_SOURCE_TELL_WRITEZIP_SOURCE_WRITEZIP_SOURCE_SUPPORTS_REOPENZIP_SOURCE_ERROR
will be called to retrieve the error code. On success, commands return 0,
unless specified otherwise in the description above.
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_ACCEPT_EMPTY,
ZIP_SOURCE_GET_FILE_ATTRIBUTES, and
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.
NULL is returned and the error code in
archive or error is set to
indicate the error (unless it is NULL).
zip_source_function() fails if:
ZIP_ER_MEMORY]zip_source_function() and
zip_source_function_create() were added in libzip 1.0.
| January 5, 2023 | NiH |