api.c File Reference

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.