"Fossies" - the Fresh Open Source Software Archive 
Member "libextractor-1.11/src/main/extractor_ipc.h" (30 Jan 2021, 12596 Bytes) of package /linux/privat/libextractor-1.11.tar.gz:
As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style:
standard) with prefixed line numbers and
code folding option.
Alternatively you can here
view or
download the uninterpreted source code file.
For more information about "extractor_ipc.h" see the
Fossies "Dox" file reference documentation.
1 /*
2 This file is part of libextractor.
3 Copyright (C) 2012 Vidyut Samanta and Christian Grothoff
4
5 libextractor is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version.
9
10 libextractor is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with libextractor; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19 */
20 /**
21 * @file main/extractor_ipc.h
22 * @brief IPC with plugin (OS-independent API)
23 * @author Christian Grothoff
24 *
25 * @detail
26 * The IPC communication between plugins and the main library works
27 * as follows. Each message begins with a 1-character opcode which
28 * specifies the message type. The main library starts the plugins
29 * by forking the helper process and establishes two pipes for
30 * communication in both directions.
31 * First, the main library send an 'INIT_STATE' message
32 * to the plugin. The start message specifies the name (and size)
33 * of a shared memory segment which will contain parts of the (uncompressed)
34 * data of the file that is being processed. The same shared memory
35 * segment is used throughout the lifetime of the plugin.
36 *
37 * Then, the following messages are exchanged for each file.
38 * First, an EXTRACT_START message is sent with the specific
39 * size of the file (or -1 if unknown) and the number of bytes
40 * ready in the shared memory segment. The plugin then answers
41 * with either:
42 * 1) MESSAGE_DONE to indicate that no further processing is
43 * required for this file; the IPC continues with the
44 * EXTRACT_START message for the next file afterwards;
45 * 2) MESSAGE_SEEK to indicate that the plugin would like to
46 * read data at a different offset; the main library can
47 * then either
48 * a) respond with a MESSAGE_DISCARD_STATE to
49 * tell the plugin to abort processing (the next message will
50 * then be another EXTRACT_START)
51 * b) respond with a MESSAGE_UPDATED_SHM which notifies the
52 * plugin that the shared memory segment was moved to a
53 * different location in the overall file; the target of the
54 * seek should now be within the new range (but does NOT have
55 * to be at the beginning of the seek)
56 * 3) MESSAGE_META to provide extracted meta data to the main
57 * library. The main library can then either:
58 * a) respond with a MESSAGE_DISCARD_STATE to
59 * tell the plugin to abort processing (the next message will
60 * then be another EXTRACT_START)
61 * b) respond with a MESSAGE_CONTINUE_EXTRACTING to
62 * tell the plugin to continue extracting meta data; in this
63 * case, the plugin is then expected to produce another
64 * MESSAGE_DONE, MESSAGE_SEEK or MESSAGE_META round of messages.
65 */
66 #ifndef EXTRACTOR_IPC_H
67 #define EXTRACTOR_IPC_H
68
69 #include "extractor_datasource.h"
70
71
72 /**
73 * How long do we allow an individual meta data object to be?
74 * Used to guard against (broken) plugns causing us to use
75 * excessive amounts of memory.
76 */
77 #define MAX_META_DATA 32 * 1024 * 1024
78
79 /**
80 * Maximum length of a shared memory object name
81 */
82 #define MAX_SHM_NAME 255
83
84 /**
85 * Sent from LE to a plugin to initialize it (opens shm).
86 */
87 #define MESSAGE_INIT_STATE 0x00
88
89 /**
90 * IPC message send to plugin to initialize SHM.
91 */
92 struct InitMessage
93 {
94 /**
95 * Set to #MESSAGE_INIT_STATE.
96 */
97 unsigned char opcode;
98
99 /**
100 * Always zero.
101 */
102 unsigned char reserved;
103
104 /**
105 * Always zero.
106 */
107 uint16_t reserved2;
108
109 /**
110 * Name of the shared-memory name.
111 */
112 uint32_t shm_name_length;
113
114 /**
115 * Maximum size of the shm map.
116 */
117 uint32_t shm_map_size;
118
119 /* followed by name of the SHM */
120 };
121
122
123 /**
124 * Sent from LE to a plugin to tell it extracting
125 * can now start. The SHM will point to offset 0
126 * of the file.
127 */
128 #define MESSAGE_EXTRACT_START 0x01
129
130 /**
131 * IPC message send to plugin to start extracting.
132 */
133 struct StartMessage
134 {
135 /**
136 * Set to #MESSAGE_EXTRACT_START.
137 */
138 unsigned char opcode;
139
140 /**
141 * Always zero.
142 */
143 unsigned char reserved;
144
145 /**
146 * Always zero.
147 */
148 uint16_t reserved2;
149
150 /**
151 * Number of bytes ready in SHM.
152 */
153 uint32_t shm_ready_bytes;
154
155 /**
156 * Overall size of the file.
157 */
158 uint64_t file_size;
159
160 };
161
162 /**
163 * Sent from LE to a plugin to tell it that shm contents
164 * were updated.
165 */
166 #define MESSAGE_UPDATED_SHM 0x02
167
168 /**
169 * IPC message send to plugin to notify it about a change in the SHM.
170 */
171 struct UpdateMessage
172 {
173 /**
174 * Set to #MESSAGE_UPDATED_SHM.
175 */
176 unsigned char opcode;
177
178 /**
179 * Always zero.
180 */
181 unsigned char reserved;
182
183 /**
184 * Always zero.
185 */
186 uint16_t reserved2;
187
188 /**
189 * Number of bytes ready in SHM.
190 */
191 uint32_t shm_ready_bytes;
192
193 /**
194 * Offset of the shm in the overall file.
195 */
196 uint64_t shm_off;
197
198 /**
199 * Overall size of the file.
200 */
201 uint64_t file_size;
202
203 };
204
205 /**
206 * Sent from plugin to LE to tell LE that plugin is done
207 * analyzing current file and will send no more data.
208 * No message format as this is only one byte.
209 */
210 #define MESSAGE_DONE 0x03
211
212 /**
213 * Sent from plugin to LE to tell LE that plugin needs
214 * to read a different part of the source file.
215 */
216 #define MESSAGE_SEEK 0x04
217
218 /**
219 * IPC message send to plugin to start extracting.
220 */
221 struct SeekRequestMessage
222 {
223 /**
224 * Set to #MESSAGE_SEEK.
225 */
226 unsigned char opcode;
227
228 /**
229 * Always zero.
230 */
231 unsigned char reserved;
232
233 /**
234 * 'whence' value for the seek operation;
235 * 0 = SEEK_SET, 1 = SEEK_CUR, 2 = SEEK_END.
236 * Note that 'SEEK_CUR' is never used here.
237 */
238 uint16_t whence;
239
240 /**
241 * Number of bytes requested for SHM.
242 */
243 uint32_t requested_bytes;
244
245 /**
246 * Requested offset; a positive value from the end of the
247 * file is used of 'whence' is SEEK_END; a postive value
248 * from the start is used of 'whence' is SEEK_SET.
249 * 'SEEK_CUR' is never used.
250 */
251 uint64_t file_offset;
252
253 };
254
255 /**
256 * Sent from plugin to LE to tell LE about metadata discovered.
257 */
258 #define MESSAGE_META 0x05
259
260 /**
261 * Plugin to parent: metadata discovered
262 */
263 struct MetaMessage
264 {
265 /**
266 * Set to #MESSAGE_META.
267 */
268 unsigned char opcode;
269
270 /**
271 * Always zero.
272 */
273 unsigned char reserved;
274
275 /**
276 * An 'enum EXTRACTOR_MetaFormat' in 16 bits.
277 */
278 uint16_t meta_format;
279
280 /**
281 * An 'enum EXTRACTOR_MetaType' in 16 bits.
282 */
283 uint16_t meta_type;
284
285 /**
286 * Length of the mime type string.
287 */
288 uint16_t mime_length;
289
290 /**
291 * Size of the value.
292 */
293 uint32_t value_size;
294
295 /* followed by mime_length bytes of 0-terminated
296 mime-type (unless mime_length is 0) */
297
298 /* followed by value_size bytes of value */
299
300 };
301
302 /**
303 * Sent from LE to plugin to make plugin discard its state
304 * (extraction aborted by application). Only one byte.
305 * Plugin should get ready for next 'StartMessage' after this.
306 * (sent in response to META data or SEEK requests).
307 */
308 #define MESSAGE_DISCARD_STATE 0x06
309
310 /**
311 * Sent from LE to plugin to make plugin continue extraction.
312 * (sent in response to META data).
313 */
314 #define MESSAGE_CONTINUE_EXTRACTING 0x07
315
316
317 /**
318 * Definition of an IPC communication channel with
319 * some plugin.
320 */
321 struct EXTRACTOR_Channel;
322
323 /**
324 * Definition of a shared memory area.
325 */
326 struct EXTRACTOR_SharedMemory;
327
328
329 /**
330 * Create a shared memory area.
331 *
332 * @param size size of the shared area
333 * @return NULL on error
334 */
335 struct EXTRACTOR_SharedMemory *
336 EXTRACTOR_IPC_shared_memory_create_ (size_t size);
337
338
339 /**
340 * Destroy shared memory area.
341 *
342 * @param shm memory area to destroy
343 * @return NULL on error
344 */
345 void
346 EXTRACTOR_IPC_shared_memory_destroy_ (struct EXTRACTOR_SharedMemory *shm);
347
348
349 /**
350 * Change the reference counter for this shm instance.
351 *
352 * @param shm instance to update
353 * @param delta value to change RC by
354 * @return new RC
355 */
356 unsigned int
357 EXTRACTOR_IPC_shared_memory_change_rc_ (struct EXTRACTOR_SharedMemory *shm,
358 int delta);
359
360
361 /**
362 * Initialize shared memory area from data source.
363 *
364 * @param shm memory area to initialize
365 * @param ds data source to use for initialization
366 * @param off offset to use in data source
367 * @param size number of bytes to copy
368 * @return -1 on error, otherwise number of bytes copied
369 */
370 ssize_t
371 EXTRACTOR_IPC_shared_memory_set_ (struct EXTRACTOR_SharedMemory *shm,
372 struct EXTRACTOR_Datasource *ds,
373 uint64_t off,
374 size_t size);
375
376
377 /**
378 * Query datasource for current position
379 *
380 * @param ds data source to query
381 * @return current position in the datasource or UINT_MAX on error
382 */
383 uint64_t
384 EXTRACTOR_datasource_get_pos_ (struct EXTRACTOR_Datasource *ds);
385
386
387 /**
388 * Create a channel to communicate with a process wrapping
389 * the plugin of the given name. Starts the process as well.
390 *
391 * @param plugin the plugin
392 * @param shm memory to share with the process
393 * @return NULL on error, otherwise IPC channel
394 */
395 struct EXTRACTOR_Channel *
396 EXTRACTOR_IPC_channel_create_ (struct EXTRACTOR_PluginList *plugin,
397 struct EXTRACTOR_SharedMemory *shm);
398
399
400 /**
401 * Destroy communication channel with a plugin/process. Also
402 * destroys the process.
403 *
404 * @param channel channel to communicate with the plugin
405 */
406 void
407 EXTRACTOR_IPC_channel_destroy_ (struct EXTRACTOR_Channel *channel);
408
409
410 /**
411 * Send data via the given IPC channel (blocking).
412 *
413 * @param channel channel to communicate with the plugin
414 * @param buf data to send
415 * @param size number of bytes in buf to send
416 * @return -1 on error, number of bytes sent on success
417 * (never does partial writes)
418 */
419 ssize_t
420 EXTRACTOR_IPC_channel_send_ (struct EXTRACTOR_Channel *channel,
421 const void *data,
422 size_t size);
423
424
425 /**
426 * Handler for a message from one of the plugins.
427 *
428 * @param cls closure
429 * @param plugin plugin of the channel sending the message
430 * @param meta_type type of the meta data
431 * @param meta_format format of the meta data
432 * @param mime mime string send from the plugin
433 * @param value 'data' send from the plugin
434 * @param value_len number of bytes in 'value'
435 */
436 typedef void (*EXTRACTOR_ChannelMessageProcessor) (void *cls,
437 struct EXTRACTOR_PluginList *
438 plugin,
439 enum EXTRACTOR_MetaType
440 meta_type,
441 enum EXTRACTOR_MetaFormat
442 meta_format,
443 const char *mime,
444 const void *value,
445 size_t value_len);
446
447
448 /**
449 * Process a reply from channel (seek request, metadata and done message)
450 *
451 * @param plugin plugin this communication is about
452 * @param buf buffer with data from IPC channel
453 * @param size number of bytes in buffer
454 * @param proc metadata callback
455 * @param proc_cls callback cls
456 * @return number of bytes processed, -1 on error
457 */
458 ssize_t
459 EXTRACTOR_IPC_process_reply_ (struct EXTRACTOR_PluginList *plugin,
460 const void *data,
461 size_t size,
462 EXTRACTOR_ChannelMessageProcessor proc,
463 void *proc_cls);
464
465
466 /**
467 * Receive data from any of the given IPC channels (blocking).
468 * Wait for one of the plugins to reply.
469 *
470 * @param channels array of channels, channels that break may be set to NULL
471 * @param num_channels length of the 'channels' array
472 * @param proc function to call to process messages (may be called
473 * more than once)
474 * @param proc_cls closure for 'proc'
475 * @return -1 on error (i.e. no response in 10s), 1 on success
476 */
477 int
478 EXTRACTOR_IPC_channel_recv_ (struct EXTRACTOR_Channel **channels,
479 unsigned int num_channels,
480 EXTRACTOR_ChannelMessageProcessor proc,
481 void *proc_cls);
482
483
484 #endif