API-CHANGES.md

   1 # libzip API changes
   2
   3 This file describes changes in the libzip API and how to adapt your
   4 code for them.
   5
   6 You can define `ZIP_DISABLE_DEPRECATED` before including `<zip.h>` to hide
   7 prototypes for deprecated functions, to find out about functions that
   8 might be removed at some point.
   9
  10 ## Changed in libzip-1.10.0
  11
  12 ### deprecated `zip_source_zip` and `zip_source_zip_create`
  13
  14 These functions were replaced with `zip_source_zip_file` and `zip_source_zip_file_create`. The implicit handling of the flag `ZIP_FL_COMPRESSED` was removed, the flag can now be specified explicitly.
  15
  16 If you want to get the compressed data for the whole file, use
  17
  18 ```C
  19 zip_source_zip_file(za, source_archive, source_index, ZIP_FL_COMPRESSED, 0, -1, NULL)
  20 ```
  21
  22 ## Changed in libzip-1.0
  23
  24 ### new type `zip_error_t`
  25
  26 Error information is stored in the newly public type `zip_error_t`. Use
  27 this to access information about an error, instead of the deprecated
  28 functions that operated on two ints.
  29
  30 deprecated functions:
  31 - `zip_error_get_sys_type()`
  32 - `zip_error_get()`
  33 - `zip_error_to_str()`
  34 - `zip_file_error_get()`
  35
  36 See their man pages for instructions on how to replace them.
  37
  38 The most common affected use is `zip_open`. The new recommended usage
  39 is:
  40
  41 ```c
  42 int err;
  43 if ((za = zip_open(archive, flags, &err)) == NULL) {
  44         zip_error_t error;
  45         zip_error_init_with_code(&error, err);
  46         fprintf(stderr, "can't open zip archive '%s': %s\n", archive, zip_error_strerror(&error));
  47         zip_error_fini(&error);
  48 }
  49 ```
  50
  51 ### more typedefs
  52
  53 The following typedefs have been added for better readability:
  54
  55 ```c
  56 typedef struct zip zip_t;
  57 typedef struct zip_file zip_file_t;
  58 typedef struct zip_source zip_source_t;
  59 typedef struct zip_stat zip_stat_t;
  60 ```
  61
  62 This means you can use "`zip_t`" instead of "`struct zip`", etc.
  63
  64
  65 ### torrentzip support removed
  66
  67 torrentzip depends on a particular zlib version which is by now quite
  68 old.
  69
  70 ## Changed in libzip-0.11
  71
  72 ### new type `zip_flags_t`
  73
  74 The functions which have flags now use the `zip_flags_t` type for this.
  75 All old flags fit; you need only to adapt code if you were saving flags in a
  76 local variable. Use `zip_flags_t` for such a variable.
  77 This affects:
  78 - `zip_fopen()`
  79 - `zip_fopen_encrypted()`
  80 - `zip_fopen_index()`
  81 - `zip_fopen_index_encrypted()`
  82 - `zip_get_archive_comment()`
  83 - `zip_get_archive_flag()`
  84 - `zip_get_num_entries()`
  85 - `zip_get_name()`
  86 - `zip_name_locate()`
  87 - `zip_set_archive_flag()`
  88 - `zip_source_zip()`
  89 - `zip_stat()`
  90 - `zip_stat_index()`
  91
  92 #### `ZIP_FL_*`, `ZIP_AFL_*`, `ZIP_STAT_*` are now unsigned constants
  93
  94 To match the new `zip_flags_t` type.
  95
  96 #### `zip_add()`, `zip_add_dir()`
  97
  98 These functions were replaced with `zip_file_add()` and `zip_dir_add()`, respectively,
  99 to add a flags argument.
 100
 101 #### `zip_rename()`, `zip_replace()`
 102
 103 These functions were replaced with `zip_file_rename()` and `zip_file_replace()`,
 104 respectively, to add a flags argument.
 105
 106 #### `zip_get_file_comment()`
 107
 108 This function was replaced with `zip_file_get_comment()`; one argument was promoted from
 109 `int` to `zip_uint32_t`, the other is now a `zip_flags_t`.
 110
 111 #### `zip_set_file_comment()`
 112
 113 This function was replaced with `zip_file_set_comment()`; an argument was promoted from
 114 `int` to `zip_uint16_t`, and a `zip_flags_t` argument was added.
 115
 116 ### integer type size changes
 117
 118 Some argument and return values were not the right size or sign.
 119
 120 #### `zip_name_locate()`
 121
 122 The return value was `int`, which can be too small. The function now returns `zip_int64_t`.
 123
 124
 125 #### `zip_get_num_entries()`
 126
 127 The return type is now signed, to allow signaling errors.
 128
 129 #### `zip_set_archive_comment()`
 130
 131 The last argument changed from `int` to `zip_uint16_t`.
 132
 133 ### extra field handling rewritten
 134
 135 The `zip_get_file_extra()` and `zip_set_file_extra()` functions were removed.
 136 They only worked on the whole extra field set.
 137
 138 Instead, you can now set, get, count, and delete each extra field separately,
 139 using the functions:
 140 - `zip_file_extra_field_delete()`
 141 - `zip_file_extra_field_delete_by_id()`
 142 - `zip_file_extra_field_get()`
 143 - `zip_file_extra_field_get_by_id()`
 144 - `zip_file_extra_fields_count()`
 145 - `zip_file_extra_fields_count_by_id()`
 146 - `zip_file_extra_field_set()`
 147
 148 Please read the corresponding man pages for details.
 149
 150 ### new functions
 151
 152 #### `zip_discard()`
 153
 154 The new `zip_discard()` function closes an archive without committing the
 155 scheduled changes.
 156
 157 #### `zip_set_file_compression()`
 158
 159 The new `zip_set_file_compression()` function allows setting compression
 160 levels for files.
 161
 162 ### argument changes
 163
 164 #### file names
 165
 166 File names arguments are now allowed to be `NULL` to have an empty file name.
 167 This mostly affects `zip_file_add()`, `zip_dir_add()`, and `zip_file_rename()`.
 168
 169 For `zip_get_name()`, `zip_file_get_comment()`, and `zip_get_archive_comment()`, if
 170 the file name or comment is empty, a string of length 0 is returned.
 171 `NULL` is returned for errors only.
 172
 173 Previously, `NULL` was returned for empty/unset file names and comments and
 174 errors, leaving no way to differentiate between the two.