                                  UMF Example download
                                  ====================

Contents of the ZIP file
========================

Most of the files in this ZIP correspond to the UMF library and some associated test files.

   umf-lib.c and umf-lib.h are the actual UMF library.

   umf-lib.hpp is a C++ wrapper for the library.

   umf-lib-test.c and umf-ccp-lib-test.cpp are test files for exercising the library.  They
        give an insight into how the library can be used.

   test-msg.c includes the tag information generated by umf2tags.exe.

   umflib.dsw and umflib.dsp are the Visual C++ project files to tie these together.


The code has been developed on Visual C++ 5, but should work with most compilers. For 
example, it has been successfully tested on GCC version 2.95.2. 

If you find any bugs, please report them to: 

     umf-lib-bugs@tech-know-ware.com 


The definition for the test message is contained in test-message-definition.txt and 
test-definition-definition-2.txt.  As yet it does not follow any particular application
analogy and the parameters are somewhat arbitrary.

umf2tags.exe is the compiler that takes the message definition files and generates the 
tag information (the output of which is included in test-msg.c).

umf2tags.bat is a DOS batch file for running umf2tags.exe with the right file names
for the test application.


Using the library
=================

The API functions for the library are all present in umf-lib.c and the names start 
with fumf_.  Each API function includes a description of what it does.

The following steps illustrate how to use the library on an encoded message. 

  1.  Check that you have a complete message. This can be done using some application 
      specific technique, or using the UMF standard method. If the UMF standard 
      method is used, then the completeness of the UMF message can be checked by 
      calling fumf_is_message_complete. 

  2.  Create an instance of the parse control structure sumf_prse_ctrl. 

  3.  Parse the message by calling the function fumf_parse_message. 

  4.  To navigate to various parts in the message, use the location setting 
      functions fumf_set_location, fumf_restore_location. 

  5.  Use the parameter reading functions to read the deisred parameters. 

  6.  Once all parameters have been read, release the parsing information by calling 
      fumf_release.

It is worth looking at the code in umf-lib-test.c for example of how the code works.