File: export.h

package info (click to toggle)
zapping 0.10~cvs6-2
  • links: PTS
  • area: main
  • in suites: lenny
  • size: 9,856 kB
  • ctags: 11,841
  • sloc: ansic: 111,154; asm: 11,770; sh: 9,812; xml: 2,742; makefile: 1,283; perl: 488
file content (402 lines) | stat: -rw-r--r-- 11,488 bytes parent folder | download | duplicates (6)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
/*
 *  libzvbi - Export modules
 *
 *  Copyright (C) 2001, 2002, 2003, 2004 Michael H. Schimek
 *
 *  Based on code from AleVT 1.5.1
 *  Copyright (C) 1998, 1999 Edgar Toernig <froese@gmx.de>
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

/* $Id: export.h,v 1.37 2005/09/01 01:40:52 mschimek Exp $ */

#ifndef __ZVBI3_EXPORT_H__
#define __ZVBI3_EXPORT_H__

#include <stdarg.h>		/* va_list */
#include <stdio.h>		/* FILE */
#include "macros.h"
#include "bcd.h"		/* vbi3_pgno, vbi3_subno */
#include "link.h"		/* vbi3_link */
#include "pdc.h"		/* vbi3_preselection */
#include "page.h"		/* vbi3_page */
#include "vbi_decoder.h"	/* vbi3_decoder */

VBI3_BEGIN_DECLS

/**
 * @ingroup Export
 * @brief Export context.
 *
 * The contents of this structure are private.
 * Call vbi3_export_new() to allocate an export module instance.
 */
typedef struct _vbi3_export vbi3_export;

/**
 * @ingroup Export
 * @brief Information about an export module.
 *
 * You can obtain this information with vbi3_export_info_enum().
 */
typedef struct vbi3_export_info {
	/**
	 * Unique (within this library) keyword identifying
	 * this export module, a NUL terminated ASCII string.
	 */
	const char *		keyword;
	/**
	 * Localized name of the export module for the user interface. Can
	 * be @c NULL if the option is not supposed to be listed in the UI.
	 */
	const char *		label;
	/**
	 * A localized description of the option for the user,
	 * can be @c NULL.
	 */
	const char *		tooltip;
	/**
	 * Description of the export format as MIME type,
	 * a NUL terminated ASCII string, for example "text/html".
	 * Can be @c NULL if no MIME type applicable.
	 */
	const char *		mime_type;
	/**
	 * Suggested filename extension, a NUL terminated ASCII string.
	 * Multiple strings are possible, separated by comma. The first
	 * string is preferred. Example: "html,htm". Can be @c NULL.
	 */
	const char *		extension;
	/**
	 * The file format is open, it can contain more than one
	 * vbi3_page. Call vbi3_export_stdio() with a NULL vbi3_page
	 * pointer to finalize the file.
	 */
	vbi3_bool		open_format;
} vbi3_export_info;

/**
 * @ingroup Export
 */
typedef enum {
	/**
	 * A boolean value, either @c TRUE (1) or @c FALSE (0).
	 * <table>
	 * <tr><td>Type:</td><td>int</td></tr>
	 * <tr><td>Default:</td><td>def.num</td></tr>
	 * <tr><td>Bounds:</td><td>min.num (0) ... max.num (1),
	 * step.num (1)</td></tr>
	 * <tr><td>Menu:</td><td>%NULL</td></tr>
	 * </table>
	 */
	VBI3_OPTION_BOOL = 1,
	/**
	 * A signed integer value. When only a few discrete values rather than
	 * a range are permitted @p menu points to a vector of integers. Note
	 * the option is still set by value, not by menu index. Setting the
	 * value may fail, or it may be replaced by the closest possible.
	 * <table>
	 * <tr><td>Type:</td><td>int</td></tr>
	 * <tr><td>Default:</td><td>def.num or menu.num[def.num]</td></tr>
	 * <tr><td>Bounds:</td><td>min.num ... max.num, step.num or menu</td>
	 * </tr>
	 * <tr><td>Menu:</td><td>%NULL or menu.num[min.num ... max.num],
	 * step.num (1)</td></tr>
	 * </table>
	 */
	VBI3_OPTION_INT,
	/**
	 * A real value, optional a vector of suggested values.
	 * <table>
	 * <tr><td>Type:</td><td>double</td></tr>
	 * <tr><td>Default:</td><td>def.dbl or menu.dbl[def.num]</td></tr>
	 * <tr><td>Bounds:</td><td>min.dbl ... max.dbl,
	 * step.dbl or menu</td></tr>
	 * <tr><td>Menu:</td><td>%NULL or menu.dbl[min.num ... max.num],
	 * step.num (1)</td></tr>
	 * </table>
	 */
	VBI3_OPTION_REAL,
	/**
	 * A null terminated string. Note the menu version differs from
	 * VBI3_OPTION_MENU in its argument, which is the string itself.
	 * For example:
	 * @code
	 * menu.str[0] = "red"
	 * menu.str[1] = "blue"
	 * ... and the option may accept other strings not explicitely listed.
	 * @endcode
	 * <table>
	 * <tr><td>Type:</td><td>char *</td></tr>
	 * <tr><td>Default:</td><td>def.str or menu.str[def.num]</td></tr>
	 * <tr><td>Bounds:</td><td>not applicable</td></tr>
	 * <tr><td>Menu:</td><td>%NULL or menu.str[min.num ... max.num],
	 * step.num (1)</td></tr>
	 * </table>
	 */
	VBI3_OPTION_STRING,
	/**
	 * Choice between a number of named options. For example:
	 * @code
	 * menu.str[0] = "up"
	 * menu.str[1] = "down"
	 * menu.str[2] = "strange"
	 * @endcode
	 * <table>
	 * <tr><td>Type:</td><td>int</td></tr>
	 * <tr><td>Default:</td><td>def.num</td></tr>
	 * <tr><td>Bounds:</td><td>min.num (0) ... max.num, 
	 *    step.num (1)</td></tr>
	 * <tr><td>Menu:</td><td>menu.str[min.num ... max.num],
	 *    step.num (1).
	 * The menu strings are localized.
	 * </td></tr>
	 * </table>
	 */
	VBI3_OPTION_MENU
} vbi3_option_type;

/**
 * @ingroup Export
 * @brief Result of an option query.
 */
typedef union {
	int			num;
	double			dbl;
	char *			str;
} vbi3_option_value;

/**
 * @ingroup Export
 * @brief Option menu types.
 */
typedef union {
	int *			num;
	double *		dbl;
	char **			str;
} vbi3_option_value_ptr;

/**
 * @ingroup Export
 * @brief Information about an export option.
 *
 * Clients can access known options by keyword, or enumerate unknown
 * options and use the information in this structure for proper
 * presentation and access.
 *
 * You can obtain this information with vbi3_export_option_info_enum().
 */
typedef struct {
	/** @see vbi3_option_type */
  	vbi3_option_type		type;
	/**
	 * Unique (within the export module) keyword to identify
	 * this option, a NUL terminated ASCII string.
	 */
	const char *		keyword;
	/**
	 * Localized name of the option for the user interface. Can
	 * be @c NULL if the option is not supposed to be listed in the UI.
	 */
	const char *		label;
	/** @see vbi3_option_type */
	union {
		int			num;
		double			dbl;
		const char *		str;
	}			def;
	/** @see vbi3_option_type */
	union {
		int			num;
		double			dbl;
	}			min, max, step;
	/** @see vbi3_option_type */
	union {
		int *			num;
		double *		dbl;
		const char **		str;
	}			menu;
	/**
	 * A localized description of the option for the user,
	 * can be @c NULL.
	 */
	const char *		tooltip;
} vbi3_option_info;

/**
 * @param e Export context passed to vbi3_export_stdio() or
 *   other output functions.
 * @param user_data User pointer passed through by
 *   vbi3_export_set_link_cb().
 * @param fp Output stream.
 * @param link Structure describing the link.
 *
 * Export modules call this type of function to write a link text
 * with metadata. Might do something like this:
 * @code
 * if (VBI3_LINK_HTTP == link->type)
 *         fprintf (fp, "<a href="%s">%s</a>", link->url, link->text);
 * @endcode
 *
 * @returns
 * FALSE on failure, which causes the export module to abort and
 * return FALSE to its caller.
 */
typedef vbi3_bool
vbi3_export_link_cb		(vbi3_export *		e,
				 void *			user_data,
				 FILE *			fp,
				 const vbi3_link *	lnk);
/**
 * @param e Export context passed to vbi3_export_stdio() or
 *   other output functions.
 * @param user_data User pointer passed through by
 *   vbi3_export_set_pdc_cb().
 * @param fp Output stream.
 * @param ps Structure describing the program.
 * @param text Text of the link.
 *
 * Export modules call this type of function to write a PDC
 * preselection text with metadata.
 *
 * @returns
 * FALSE on failure, which causes the export module to abort and
 * return FALSE to its caller.
 */
typedef vbi3_bool
vbi3_export_pdc_cb		(vbi3_export *		e,
				 void *			user_data,
				 FILE *			fp,
				 const vbi3_preselection *ps,
				 const char *		text);

/**
 * @addtogroup Export
 * @{
 */
extern const char *
vbi3_export_errstr		(vbi3_export *		e)
  __attribute__ ((_vbi3_nonnull (1)));
extern vbi3_bool
vbi3_export_stdio		(vbi3_export *		e,
				 FILE *			fp,
				 const vbi3_page *	pg)
  __attribute__ ((_vbi3_nonnull (1, 2))); /* sic */
extern vbi3_bool
vbi3_export_file			(vbi3_export *		e,
				 const char *		name,
				 const vbi3_page *	pg)
  __attribute__ ((_vbi3_nonnull (1, 2, 3)));
#ifndef ZAPPING8
extern vbi3_bool
vbi3_export_stream_close		(vbi3_export *		e)
  __attribute__ ((_vbi3_nonnull (1)));
extern vbi3_bool
vbi3_export_stream_stdio_va_list	(vbi3_export *		e,
				 FILE *			fp,
				 vbi3_decoder *		vbi,
	    			 vbi3_pgno		pgno,
				 vbi3_subno		subno,
				 va_list		format_options)
  __attribute__ ((_vbi3_nonnull (1, 2, 3)));
extern vbi3_bool
vbi3_export_stream_stdio		(vbi3_export *		e,
				 FILE *			fp,
				 vbi3_decoder *		vbi,
	    			 vbi3_pgno		pgno,
				 vbi3_subno		subno,
				 ...)
  __attribute__ ((_vbi3_nonnull (1, 2, 3),
		  _vbi3_sentinel));
extern vbi3_bool
vbi3_export_stream_file_va_list	(vbi3_export *		e,
				 const char *		name,
				 vbi3_decoder *		vbi,
	    			 vbi3_pgno		pgno,
				 vbi3_subno		subno,
				 va_list		format_options)
  __attribute__ ((_vbi3_nonnull (1, 2, 3)));
extern vbi3_bool
vbi3_export_stream_file		(vbi3_export *		e,
				 const char *		name,
				 vbi3_decoder *		vbi,
	    			 vbi3_pgno		pgno,
				 vbi3_subno		subno,
				 ...)
  __attribute__ ((_vbi3_nonnull (1, 2, 3),
		  _vbi3_sentinel));
#endif /* !ZAPPING8 */
extern void
vbi3_export_set_link_cb		(vbi3_export *		e,
				 vbi3_export_link_cb *	callback,
				 void *			user_data)
  __attribute__ ((_vbi3_nonnull (1)));
extern void
vbi3_export_set_pdc_cb		(vbi3_export *		e,
				 vbi3_export_pdc_cb *	callback,
				 void *			user_data)
  __attribute__ ((_vbi3_nonnull (1)));
extern void
vbi3_export_set_timestamp	(vbi3_export *		e,
				 double			timestamp)
  __attribute__ ((_vbi3_nonnull (1)));
extern vbi3_bool
vbi3_export_option_menu_get	(vbi3_export *		e,
				 const char *		keyword,
				 unsigned int *		entry)
  __attribute__ ((_vbi3_nonnull (1, 2, 3)));
extern vbi3_bool
vbi3_export_option_menu_set	(vbi3_export *		e,
				 const char *		keyword,
				 unsigned int		entry)
  __attribute__ ((_vbi3_nonnull (1, 2)));
extern vbi3_bool
vbi3_export_option_get		(vbi3_export *		e,
				 const char *		keyword,
				 vbi3_option_value *	value)
  __attribute__ ((_vbi3_nonnull (1, 2, 3)));
extern vbi3_bool
vbi3_export_option_set		(vbi3_export *		e,
				 const char *		keyword,
				 ...)
  __attribute__ ((_vbi3_nonnull (1, 2)));
extern const vbi3_option_info *
vbi3_export_option_info_enum	(vbi3_export *		e,
				 unsigned int		indx)
  __attribute__ ((_vbi3_nonnull (1)));
extern const vbi3_option_info *
vbi3_export_option_info_by_keyword
				(vbi3_export *		e,
				 const char *		keyword)
  __attribute__ ((_vbi3_nonnull (1)));
extern const vbi3_export_info *
vbi3_export_info_enum		(unsigned int		indx);
extern const vbi3_export_info *
vbi3_export_info_by_keyword	(const char *		keyword);
extern const vbi3_export_info *
vbi3_export_info_from_export	(const vbi3_export *	e)
  __attribute__ ((_vbi3_nonnull (1)));
extern void
vbi3_export_delete		(vbi3_export *		e);
extern vbi3_export *
vbi3_export_new			(const char *		keyword,
				 char **		errstr)
  __attribute__ ((malloc));
/** @} */

VBI3_END_DECLS

#endif /* __ZVBI3_EXPORT_H__ */