Main Page Alphabetical List Data Structures File List Data Fields Globals

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