OVMS3/OVMS.V3/components/zip/libzip/API-CHANGES.md

libzip API changes

This file describes changes in the libzip API and how to adapt your code for them.

You can define ZIP_DISABLE_DEPRECATED before including <zip.h> to hide prototypes for deprecated functions, to find out about functions that might be removed at some point.

Changed in libzip-1.0

new type zip_error_t

Error information is stored in the newly public type zip_error_t. Use this to access information about an error, instead of the deprecated functions that operated on two ints.

deprecated functions:

• zip_error_get_sys_type()
• zip_error_get()
• zip_error_to_str()
• zip_file_error_get()

See their man pages for instructions on how to replace them.

The most common affected use is zip_open. The new recommended usage is:

int err;
if ((za = zip_open(archive, flags, &err)) == NULL) {
	zip_error_t error;
	zip_error_init_with_code(&error, err);
	fprintf(stderr, "can't open zip archive '%s': %s\n", archive, zip_error_strerror(&error));
	zip_error_fini(&error);
}

more typedefs

The following typedefs have been added for better readability:

typedef struct zip zip_t;
typedef struct zip_file zip_file_t;
typedef struct zip_source zip_source_t;
typedef struct zip_stat zip_stat_t;

This means you can use "zip_t" instead of "struct zip", etc.

torrentzip support removed

torrentzip depends on a particular zlib version which is by now quite old.

Changed in libzip-0.11

new type zip_flags_t

The functions which have flags now use the zip_flags_t type for this. All old flags fit; you need only to adapt code if you were saving flags in a local variable. Use zip_flags_t for such a variable. This affects:

• zip_fopen()
• zip_fopen_encrypted()
• zip_fopen_index()
• zip_fopen_index_encrypted()
• zip_get_archive_comment()
• zip_get_archive_flag()
• zip_get_num_entries()
• zip_get_name()
• zip_name_locate()
• zip_set_archive_flag()
• zip_source_zip()
• zip_stat()
• zip_stat_index()

ZIP_FL_*, ZIP_AFL_*, ZIP_STAT_* are now unsigned constants

To match the new zip_flags_t type.

zip_add(), zip_add_dir()

These functions were replaced with zip_file_add() and zip_dir_add(), respectively, to add a flags argument.

zip_rename(), zip_replace()

These functions were replaced with zip_file_rename() and zip_file_replace(), respectively, to add a flags argument.

zip_get_file_comment()

This function was replaced with zip_file_get_comment(); one argument was promoted from int to zip_uint32_t, the other is now a zip_flags_t.

zip_set_file_comment()

This function was replaced with zip_file_set_comment(); an argument was promoted from int to zip_uint16_t, and a zip_flags_t argument was added.

integer type size changes

Some argument and return values were not the right size or sign.

zip_name_locate()

The return value was int, which can be too small. The function now returns zip_int64_t.

zip_get_num_entries()

The return type is now signed, to allow signaling errors.

zip_set_archive_comment()

The last argument changed from int to zip_uint16_t.

extra field handling rewritten

The zip_get_file_extra() and zip_set_file_extra() functions were removed. They only worked on the whole extra field set.

Instead, you can now set, get, count, and delete each extra field separately, using the functions:

• zip_file_extra_field_delete()
• zip_file_extra_field_delete_by_id()
• zip_file_extra_field_get()
• zip_file_extra_field_get_by_id()
• zip_file_extra_fields_count()
• zip_file_extra_fields_count_by_id()
• zip_file_extra_field_set()

Please read the corresponding man pages for details.

new functions

zip_discard()

The new zip_discard() function closes an archive without committing the scheduled changes.

zip_set_file_compression()

The new zip_set_file_compression() function allows setting compression levels for files.

argument changes

file names

File names arguments are now allowed to be NULL to have an empty file name. This mostly affects zip_file_add(), zip_dir_add(), and zip_file_rename().

For zip_get_name(), zip_file_get_comment(), and zip_get_archive_comment(), if the file name or comment is empty, a string of length 0 is returned. NULL is returned for errors only.

Previously, NULL was returned for empty/unset file names and comments and errors, leaving no way to differentiate between the two.