API-CHANGES

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