---

api.c File Reference

Functions
wmf_error_t	wmf_lite_create (wmfAPI **API_return, unsigned long flags, wmfAPI_Options *options)
wmf_error_t	wmf_lite_destroy (wmfAPI *API)
void	wmf_assert (wmfAPI *API, char *file, int line)
void	wmf_error (wmfAPI *API, char *file, int line, char *msg)
void	wmf_debug (wmfAPI *API, char *file, int line, char *msg)
void	wmf_printf (wmfAPI *API, char *msg,...)
void *	wmf_malloc (wmfAPI *API, size_t size)
void *	wmf_calloc (wmfAPI *API, size_t number, size_t size)
void *	wmf_realloc (wmfAPI *API, void *mem, size_t size)
void	wmf_free (wmfAPI *API, void *mem)
void	wmf_detach (wmfAPI *API, void *mem)
char *	wmf_strdup (wmfAPI *API, const char *str)
char *	wmf_str_append (wmfAPI *API, char *pre, char *post)
char *	wmf_strstr (const char *haystack, const char *needle)
void	wmf_status_function (wmfAPI *API, void *context, wmfStatus function)
unsigned long	wmf_strbuf_grow (wmfAPI *API)

---

Function Documentation

void wmf_assert (  wmfAPI *    API, char *    file, int    line )

Set the error state of the library to wmf_E_Assert. Parameters: API  the API handle file  file name line  line number This should only be called via the macro WMF_ASSERT(API,<expr>) which is defined (for debug builds only) as: #define WMF_ASSERT(Z,M) if (!(M)) wmf_assert (Z,__FILE__,__LINE__) i.e., if <expr> evaluates to 0 then call wmf_assert() with current file name and line number.

void* wmf_calloc (  wmfAPI *    API, size_t    number, size_t    size )

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.

void wmf_debug (  wmfAPI *    API, char *    file, int    line, char *    msg )

Print message to debug stream. Parameters: API  the API handle file  file name line  line number msg  message to print This should only be called via the macro WMF_DEBUG(API,msg) which (in debug builds only) calls wmf_debug() with the current file name and line number.

void wmf_detach (  wmfAPI *    API, void *    mem )

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().

void wmf_error (  wmfAPI *    API, char *    file, int    line, char *    msg )

Print message to error stream. Parameters: API  the API handle file  file name line  line number msg  message to print This should only be called via the macro WMF_ERROR(API,msg) which calls wmf_error() with the current file name and line number.

void wmf_free (  wmfAPI *    API, void *    mem )

Frees 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 Syntax is similar to free().

wmf_error_t wmf_lite_create (  wmfAPI **    API_return, unsigned long    flags, wmfAPI_Options *    options )

Creates and initializes an instance of the libwmf library (lite interface) 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 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. wmf_lite_create () ignores command line arguments, if any are given, and does not attempt to set up font mapping. The library should be closed using the corresponding wmf_lite_destroy () function. 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.

wmf_error_t wmf_lite_destroy (  wmfAPI *    API )

Close the device layer, if open, and release all allocated memory attached to the memory manager. Parameters: API  the API handle Returns: The final error state of the library.

void* wmf_malloc (  wmfAPI *    API, size_t    size )

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.

void wmf_printf (  wmfAPI *    API, char *    msg, ...    )

Print formatted message to debug stream. Parameters: API  the API handle msg  message to print With syntax similar to printf(), wmf_printf() prints formatted output to the debug stream.

void* wmf_realloc (  wmfAPI *    API, void *    mem, size_t    size )

(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.

void wmf_status_function (  wmfAPI *    API, void *    context, wmfStatus    function )

Set a status call-back function. Parameters: API  the API handle context  handle for user data function  call-back function The metafile player calls the status function after each record.

char* wmf_str_append (  wmfAPI *    API, char *    pre, char *    post )

Create concatenatation of two strings and attach to the API's memory manager's internal list. Parameters: API  the API handle pre  a string post  a string wmf_str_append() allocates the necessary memory via wmf_malloc(), copies pre into the string and appends post. 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.

unsigned long wmf_strbuf_grow (  wmfAPI *    API )

Increase the size of the internal string buffer. Parameters: API  the API handle libwmf maintains an internal buffer for string operations. wmf_strbuf_grow() increases the size by 64. Returns: Returns the new size of the buffer. Uses wmf_realloc(), so may set wmf_E_InsMem on failure.

char* wmf_strdup (  wmfAPI *    API, const char *    str )

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.

char* wmf_strstr (  const char *    haystack, const char *    needle )

Substring search. Parameters: haystack  a string needle  a substring to search for in haystack With syntax identical to strstr(), wmf_strstr() searches for string needle in string haystack. Returns: Pointer to substring needle found in haystack, or zero if not found.

---