Main Page Alphabetical List Data Structures File List Data Fields Globals

# api.c File Reference

## Functions
wmf_error_t | wmf_api_create (wmfAPI **API_return, unsigned long flags, wmfAPI_Options *options)
wmf_error_t | wmf_api_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, 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)
char * | wmf_help ()
unsigned long | wmf_strbuf_grow (wmfAPI *API)

## Function Documentation

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

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

wmf_error_t wmf_api_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_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().

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/>.
Returns: Returns the above as a string.

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,
|  | 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:
  hatstack | 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.