aboutsummaryrefslogtreecommitdiffstats
path: root/util/alevt/EXPORT.HOWTO
diff options
context:
space:
mode:
authorMark Purcell <msp@debian.org>2010-02-25 21:13:46 +1100
committeretobi <git@e-tobi.net>2013-09-03 09:48:46 +0200
commit665818f1969f893f05edf5b70eb1804c89b2829e (patch)
tree34ba68cee03c52d769a5a51b456b7e9d63cd091a /util/alevt/EXPORT.HOWTO
parent109c7947d6a11a2a54eff1b19615ed80ea2f0602 (diff)
parent9fe4d4ea9c054e539ab679ed2e9c076c35beb69d (diff)
downloadlinux-dvb-apps-665818f1969f893f05edf5b70eb1804c89b2829e.tar.gz
Imported Debian patch 1.1.1+rev1355-1debian/1.1.1+rev1355-1
Diffstat (limited to 'util/alevt/EXPORT.HOWTO')
-rw-r--r--util/alevt/EXPORT.HOWTO84
1 files changed, 84 insertions, 0 deletions
diff --git a/util/alevt/EXPORT.HOWTO b/util/alevt/EXPORT.HOWTO
new file mode 100644
index 0000000..b9fba67
--- /dev/null
+++ b/util/alevt/EXPORT.HOWTO
@@ -0,0 +1,84 @@
+HOW TO IMPLEMENT A NEW EXPORT MODULE:
+
+As an example look at exp-txt.c (it implements two modules which
+are pretty similar).
+
+You have to create one exported structure (struct export_module).
+This structure holds the following data:
+
+1. The name of the format (example: "ascii").
+
+2. The default extension to use for building filenames ("txt").
+
+3. A list of module options. It's a 0 terminated array of char
+pointers, one for each option (similar to argv of main).
+If an option string contains a '=', it is an option that
+requires an argument. The part after the '=' is ignored at
+the moment. Later, I want to add help messages that show
+these options strings and then the part after the '=' becomes
+useful.
+If you do not have local options, set this field to 0.
+
+4. The number of bytes for local data in the export structure.
+There you may store data collected during option parsing or
+for whatever you want.
+Don't use global variables for storing this data! With
+alevt-cap you may give:
+
+alevt-cap -format ascii,color 100 -format ascii 100
+
+to save the page in two different formats. Using global
+vars would inhibit this. The data area in struct export
+starts at the 'data' field. You have to cast it to the
+appropriate type (see the D macro in exp-txt.c).
+If you do not need local data, set this field to 0.
+
+5. An open function (or call it constructor). It is called
+when your module is needed and it is passed a struct export
+(the instance). This function may be used to initialize
+the local data in the export struct.
+If all goes well return 0. Else call export_error (see
+below) and return -1.
+If you do not need an open function, set this field to 0.
+
+6. A close function (or call it destructor). It is called
+when your module is no longer needed. If you allocated
+memory in the open func, this is the place to free it.
+If you do not need a close function, set it to 0.
+
+7. An option function. It is called for each module option
+the user has given. It is passed an option number (first
+option in the option-array gives 1, ...) and a char pointer
+to the argument for that option (0 if the option does not
+need an arg). The argument pointer keeps valid until the
+close function is called.
+If all goes well, return 0. Else call export_error and
+return -1.
+If you gave an option list at point 3 you have to specify
+this function. Else set it to 0.
+
+8. An output function. It is called to produce the output.
+It is given the file name to use and a fmt_page pointer.
+The fmt_page contains an interpreted image of the page.
+There are no control chars in it. It uses the character
+set defined by the two fonts.
+These function may be called consecutive for multiple
+pages. Don't expect one output for one open/close.
+Return codes as above... (0: ok, -1: error).
+
+The export_error function: If one of your functions wants to
+report an error, it has to use the export_error function.
+It's a printf like function to set error messages. In alevt-cap
+these messages are printed to stderr, in alevt they will be
+shown in the status line (so don't make them too long).
+
+The last step is to add your export_module structure to the
+list of modules in export.c (at the top).
+Please, make sure that this structure is the only exported
+symbol. All other things should be static.
+
+That's all. A structure describing your module and 4 functions
+(open, close, option, output) to implement it. Shouldn't be too
+complicated.
+
+Ciao, ET.