1ZIP_SOURCE_FUNCTION(3)   BSD Library Functions Manual   ZIP_SOURCE_FUNCTION(3)
2

NAME

4     zip_source_function, zip_source_function_create — create data source from
5     function
6

LIBRARY

8     libzip (-lzip)
9

SYNOPSIS

11     #include <zip.h>
12
13     zip_source_t *
14     zip_source_function(zip_t *archive, zip_source_callback fn,
15         void *userdata);
16
17     zip_source_t *
18     zip_source_function_create(zip_source_callback fn, void *userdata,
19         zip_error_t *error);
20

DESCRIPTION

22     The functions zip_source_function() and zip_source_function_create() cre‐
23     ates a zip source from the user-provided function fn, which must be of
24     the following type:
25
26     typedef zip_int64_t (*zip_source_callback)(void *userdata, void *data,
27     zip_uint64_t len, zip_source_cmd_t cmd)
28
29     archive or error are used for reporting errors and can be NULL.
30
31     When called by the library, the first argument is the userdata argument
32     supplied to the function.  The next two arguments are a buffer data of
33     size len when data is passed in or expected to be returned, or else NULL
34     and 0.  The last argument, cmd, specifies which action the function
35     should perform.
36
37     Depending on the uses, there are three useful sets of commands to be sup‐
38     ported by a zip_source_callback():
39
40     read source             Providing streamed data (for file data added to
41                             archives).  Must support ZIP_SOURCE_OPEN,
42                             ZIP_SOURCE_READ, ZIP_SOURCE_CLOSE,
43                             ZIP_SOURCE_STAT, and ZIP_SOURCE_ERROR.
44
45     seekable read source    Same as previous, but from a source allowing
46                             reading from arbitrary offsets (also for read-
47                             only zip archive).  Must additionally support
48                             ZIP_SOURCE_SEEK, ZIP_SOURCE_TELL, and
49                             ZIP_SOURCE_SUPPORTS.
50
51     read/write source       Same as previous, but additionally allowing writ‐
52                             ing (also for writable zip archives).  Must addi‐
53                             tionally support ZIP_SOURCE_BEGIN_WRITE,
54                             ZIP_SOURCE_COMMIT_WRITE,
55                             ZIP_SOURCE_ROLLBACK_WRITE, ZIP_SOURCE_SEEK_WRITE,
56                             ZIP_SOURCE_TELL_WRITE, and ZIP_SOURCE_REMOVE.
57
58   ZIP_SOURCE_ACCEPT_EMPTY
59     Return 1 if an empty source should be accepted as a valid zip archive.
60     This is the default if this command is not supported by a source.  File
61     system backed sources should return 0.
62
63   ZIP_SOURCE_BEGIN_WRITE
64     Prepare the source for writing.  Use this to create any temporary
65     file(s).
66
67   ZIP_SOURCE_BEGIN_WRITE_CLONING
68     Prepare the source for writing, keeping the first len bytes of the origi‐
69     nal file.  Only implement this command if it is more efficient than copy‐
70     ing the data, and if it does not destructively overwrite the original
71     file (you still have to be able to execute ZIP_SOURCE_ROLLBACK_WRITE).
72
73     The next write should happen at byte offset.
74
75   ZIP_SOURCE_CLOSE
76     Reading is done.
77
78   ZIP_SOURCE_COMMIT_WRITE
79     Finish writing to the source.  Replace the original data with the newly
80     written data.  Clean up temporary files or internal buffers.  Subse‐
81     quently opening and reading from the source should return the newly writ‐
82     ten data.
83
84   ZIP_SOURCE_ERROR
85     Get error information.  data points to an array of two ints, which should
86     be filled with the libzip error code and the corresponding system error
87     code for the error that occurred.  See zip_errors(3) for details on the
88     error codes.  If the source stores error information in a zip_error_t,
89     use zip_error_to_data(3) and return its return value.  Otherwise, return
90     2 * sizeof(int).
91
92   ZIP_SOURCE_FREE
93     Clean up and free all resources, including userdata.  The callback func‐
94     tion will not be called again.
95
96   ZIP_SOURCE_OPEN
97     Prepare for reading.
98
99   ZIP_SOURCE_READ
100     Read data into the buffer data of size len.  Return the number of bytes
101     placed into data on success, and zero for end-of-file.
102
103   ZIP_SOURCE_REMOVE
104     Remove the underlying file.  This is called if a zip archive is empty
105     when closed.
106
107   ZIP_SOURCE_ROLLBACK_WRITE
108     Abort writing to the source.  Discard written data.  Clean up temporary
109     files or internal buffers.  Subsequently opening and reading from the
110     source should return the original data.
111
112   ZIP_SOURCE_SEEK
113     Specify position to read next byte from, like fseek(3).  Use
114     ZIP_SOURCE_GET_ARGS(3) to decode the arguments into the following struct:
115
116     struct zip_source_args_seek {
117         zip_int64_t offset;
118         int whence;
119     };
120
121     If the size of the source's data is known, use
122     zip_source_seek_compute_offset(3) to validate the arguments and compute
123     the new offset.
124
125   ZIP_SOURCE_SEEK_WRITE
126     Specify position to write next byte to, like fseek(3).  See
127     ZIP_SOURCE_SEEK for details.
128
129   ZIP_SOURCE_STAT
130     Get meta information for the input data.  data points to an allocated
131     struct zip_stat, which should be initialized using zip_stat_init(3) and
132     then filled in.
133
134     For uncompressed, unencrypted data, all information is optional.  How‐
135     ever, fill in as much information as is readily available.
136
137     If the data is compressed, ZIP_STAT_COMP_METHOD, ZIP_STAT_SIZE, and
138     ZIP_STAT_CRC must be filled in.
139
140     If the data is encrypted, ZIP_STAT_ENCRYPTION_METHOD,
141     ZIP_STAT_COMP_METHOD, ZIP_STAT_SIZE, and ZIP_STAT_CRC must be filled in.
142
143     Information only available after the source has been read (e.g., size)
144     can be omitted in an earlier call.  NOTE: zip_source_function() may be
145     called with this argument even after being called with ZIP_SOURCE_CLOSE.
146
147     Return sizeof(struct zip_stat) on success.
148
149   ZIP_SOURCE_SUPPORTS
150     Return bitmap specifying which commands are supported.  Use
151     zip_source_make_command_bitmap(3).  If this command is not implemented,
152     the source is assumed to be a read source without seek support.
153
154   ZIP_SOURCE_TELL
155     Return the current read offset in the source, like ftell(3).
156
157   ZIP_SOURCE_TELL_WRITE
158     Return the current write offset in the source, like ftell(3).
159
160   ZIP_SOURCE_WRITE
161     Write data to the source.  Return number of bytes written.
162
163   Return Values
164     Commands should return -1 on error.  ZIP_SOURCE_ERROR will be called to
165     retrieve the error code.  On success, commands return 0, unless specified
166     otherwise in the description above.
167
168   Calling Conventions
169     The library will always issue ZIP_SOURCE_OPEN before issuing
170     ZIP_SOURCE_READ, ZIP_SOURCE_SEEK, or ZIP_SOURCE_TELL.  When it no longer
171     wishes to read from this source, it will issue ZIP_SOURCE_CLOSE.  If the
172     library wishes to read the data again, it will issue ZIP_SOURCE_OPEN a
173     second time.  If the function is unable to provide the data again, it
174     should return -1.
175
176     ZIP_SOURCE_BEGIN_WRITE or ZIP_SOURCE_BEGIN_WRITE_CLONING will be called
177     before ZIP_SOURCE_WRITE, ZIP_SOURCE_SEEK_WRITE, or ZIP_SOURCE_TELL_WRITE.
178     When writing is complete, either ZIP_SOURCE_COMMIT_WRITE or
179     ZIP_SOURCE_ROLLBACK_WRITE will be called.
180
181     ZIP_SOURCE_STAT can be issued at any time.
182
183     ZIP_SOURCE_ERROR will only be issued in response to the function return‐
184     ing -1.
185
186     ZIP_SOURCE_FREE will be the last command issued; if ZIP_SOURCE_OPEN was
187     called and succeeded, ZIP_SOURCE_CLOSE will be called before
188     ZIP_SOURCE_FREE, and similarly for ZIP_SOURCE_BEGIN_WRITE or
189     ZIP_SOURCE_BEGIN_WRITE_CLONING and ZIP_SOURCE_COMMIT_WRITE or
190     ZIP_SOURCE_ROLLBACK_WRITE.
191

RETURN VALUES

193     Upon successful completion, the created source is returned.  Otherwise,
194     NULL is returned and the error code in archive or error is set to indi‐
195     cate the error (unless it is NULL).
196

ERRORS

198     zip_source_function() fails if:
199
200     [ZIP_ER_MEMORY]    Required memory could not be allocated.
201

SEE ALSO

203     libzip(3), zip_file_add(3), zip_file_replace(3), zip_source(3),
204     zip_stat_init(3)
205

HISTORY

207     zip_source_function() and zip_source_function_create() were added in
208     libzip 1.0.
209

AUTHORS

211     Dieter Baron <dillo@nih.at> and Thomas Klausner <tk@giga.or.at>
212
213BSD                           September 17, 2019                           BSD
Impressum