Creates and initializes an instance of the libwmf library for a specified device layer.
Parameters:
API_return
pointer to a wmfAPI* (the API handle use henceforth)
flags
bitwise OR of WMF_OPT_ options
options
pointer to wmfAPI_Options structure
This is the first and necessary step when using libwmf. Options are passed via the wmfAPI_Options structure and flags. wmf_api_create allocates the wmfAPI structure and initializes the color and font tables, the metafile player, and the device layer. If successful then the pointer to the wmfAPI structure is returned via API_return, otherwise all allocated memory is released and the library exits with an appropriate error.
Returns:
The error state of the library: wmf_E_None indicates successful creation and initialization of the library, and *API_return will be non-zero. For any other error value *API_return will be zero.
Set custom metafile input-stream handler functions.
Parameters:
API
the API handle
fp_read
function to read a byte
fp_seek
function to set position
fp_tell
function to get position
user_data
handle for user data
libwmf has simple methods for reading either from file or from memory, but many applications will want to use customized variants of these. wmf_bbuf_input() enables this.
typedef int (*wmfRead) (void* user_data);
typedef int (*wmfSeek) (void* user_data,long position);
typedef long (*wmfTell) (void* user_data);
wmfRead returns unsigned char cast to int, or EOF (cf. fgetc())
wmfSeek returns (-1) on error, otherwise 0 (cf. fseek())
wmfTell returns (-1) on error, otherwise current position (cf. ftell())
Returns:
Returns the library error state (wmf_E_None on success). Possible library error state of wmf_E_Glitch, if any of the three functions is zero.
Allocate memory of specified size and attach to the API's memory manager's internal list.
Parameters:
API
the API handle
number
number or elements
size
size in bytes of memory required by one element
With syntax similar to calloc(), wmf_calloc() allocates number * size bytes of memory and adds a reference to it in the memory manager's list. To free the memory, use wmf_free().
Returns:
Pointer to new memory, or zero on failure. Sets error state wmf_E_InsMem on failure.
Detach memory attached to the API's memory manager's internal list.
Parameters:
API
the API handle
mem
pointer to memory previously allocated via the API
This removes the reference in the API's memory manager's internal list, and the memory will not, therefore, be released by wmf_api_destroy(). To free subsequently, use free().
(Must read the header first, either via wmf_scan() or by calling wmf_header_read() directly.)
Returns:
Returns the library error state (wmf_E_None on success). Possible library error states of wmf_E_Glitch, wmf_E_BadFormat (bad header), wmf_E_BadFile (no open input stream) and wmf_E_EOF (premature end-of-file).
char* wmf_help
(
void
)
Additional wmf-related options:
--wmf-error[=yes|no] switch for error reports.
--wmf-debug[=yes|no] switch for debug reports, if any.
--wmf-ignore-nonfatal[=yes|no] switch to ignore (some) non-fatal errors.
--wmf-diagnostics emit diagnostic information.
--wmf-fontdir=<path> add <path> to list of font directories.
--wmf-sys-fonts use system fonts, if any found.
--wmf-sys-fontmap=<file> use system xml-fontmap file <file>.
--wmf-xtra-fonts use non-system fonts, if any found.
--wmf-xtra-fontmap=<file> use non-system xml-fontmap file <file>.
--wmf-gs-fontmap=<file> use ghostscript file <file>.
Report bugs to <http://www.wvware.com/>.
Allocate memory of specified size and attach to the API's memory manager's internal list.
Parameters:
API
the API handle
size
size in bytes of memory required
With syntax similar to malloc(), wmf_malloc() allocates size bytes of memory and adds a reference to it in the memory manager's list. To free the memory, use wmf_free().
Returns:
Pointer to new memory, or zero on failure. Sets error state wmf_E_InsMem on failure.
Before the metafile can be played, it must be scanned - see wmf_scan().
The first time (and only the first time) the metafile is played, it first calls device_open() for the device layer specified (and initialized) in wmf_api_create(). Then, and also each subsequent time the metafile is played, it calls device_begin(), plays the metafile (with calls to various other device layer functions), and finally it calls device_end(). device_close() is only ever called via wmf_api_destroy().
d_r is recomputed, but should not change.
Returns:
Returns the library error state (wmf_E_None on success).
(Re)Allocate memory of specified size and attach to the API's memory manager's internal list.
Parameters:
API
the API handle
mem
pointer to memory previously allocated via the API
size
new size in bytes of memory required
With syntax similar to realloc(), wmf_realloc() allocates size bytes of memory and adds a reference to it in the memory manager's list. To free the memory, use wmf_free(). If mem is zero, this is equivalent to a call to wmf_malloc(). If size is zero, the memory is released via wmf_free().
Returns:
Pointer to new memory, or zero on failure. Sets error state wmf_E_InsMem on failure.
Before the metafile can be played, it must be scanned. This is because metafile headers do not always provide image size information. Although the device layer (the graphics exporter) is initialized in wmf_api_create(), the output device is not opened until after the metafile is scanned. By scanning, therefore, the device layer can be provided on opening not only with size information but also a list of colors to expect (not including those in raster images) and of other required resources, if necessary. Finally, if scanning fails, then there's certainly no point in playing the metafile.
The bounding box, in device coordinates, is returned in *d_r.
Returns:
Returns the library error state (wmf_E_None on success).
wmf_size() returns image width in *width and image height in *height. If supplied, the metafile header values are used, otherwise the width and height found by wmf_scan() are used.
Returns:
Returns the library error state (wmf_E_None on success). Possible library error state of wmf_E_Glitch (the metafile has not been scanned).
Duplicate string and attach to the API's memory manager's internal list.
Parameters:
API
the API handle
str
a string
With syntax similar to strdup(), wmf_strdup() allocates the necessary memory via wmf_malloc() and copies the string. Use wmf_free() to free the string.
Returns:
Pointer to new string, or zero on failure. Sets error state wmf_E_InsMem on failure, or wmf_E_Glitch if str is zero.
wmf_ztream_create() creates a wmfStream (a character-based output stream) for output to a file opened via zlib. (Writing compressed data to memory is not currently supported.)
Returns:
Returns a wmfStream pointer, or zero on failure. Possible library error state of wmf_E_InsMem.
1.2.9.1 written by Dimitri van Heesch,
© 1997-2001