
The makefile builds a library called libufdb.a
This library can be linked with any 3rd party program that uses the ufdbGuard API.
The build steps are:
   1. follow the build instructions in the Reference Manual.
   2. in addition, do the following:
      cd .../api 
      make
Step 1 builds the core ufdbGuard object files and excutables.
Step 2 builds the ufdbGuard API library (libufdbapi.a).

A note about multi-threaded applications.
ufdbGuard is written for multi-threaded applications.
In case that the API of ufdbGuard is to be used for a single-threaded
application, the macro UFDB_API_NO_THREADS must be defined in the Makefile.
   E.g.  CFLAGS= -DUFDB_API_NO_THREADS ...
And the program must also not be linked with the pthreads library
(do not use -lpthreads)
   E.g.  LIBRARY_OPTS= -L. -lufdbapi -lbz2 ### -lpthread

The API has minimal documentation, but the API test program has all that you need.
Read apitest.c carefully, adjust DBDIR for the local database directory.
Here is all the code that is required to initialise and use ufdbGuard.

A program that uses the ufdbGuard API needs to have its own data structure
that contains at least the following:
   UFDBusedCategory usedCategory[UFDB_MAX_CATEGORIES];	/* see 
   int numUsedCategories;

The API is initialised in applInit() that calls
initialiseCategories() once and UFDBallocThreadAdmin() for each thread.
initialiseCategories() calls UFDBloadCategory() for each category.
NOTE: A non-threaded program is seen as a single-threaded program and
hence calls UFDBallocThreadAdmin() once.
Then blockCategory() is used for each category that is used to block URLs.

After the initialisation, apitest does a number of calls to MYAPPverifyURL()
which is an example implementation of a URL verification function.

Whenever a new URL database is to be used, all categories must be reloaded with
   a call to UFDBunloadCategory() and
   a call to UFDBloadCategory().
CAVEAT: be careful with multithreaded applications and prevent parallel
lookups and a database reload.

An application can verify any valid URL.
In apitest.c the function MYAPPverifyURL() does a URL verification
and checks if the URL is part of a category by verifying each category 
(one by one).

MYAPPverifyURL() (see apitest.c) can be simplified into:
   block = 0;
   /* strip all excess information from the URL */
   UFDBstripURL( URL, strippedUrl, domain, protocol, &port );
   /* convert the URL into an internal format suitable for fast lookups */
   revUrl = UFDBgenRevURL( admin, strippedUrl );
   /* scan all categories for a match */
   for (i = 0; i < numUsedCategories; i++)
   {
      if (UFDBverifyUrlCategory( strippedUrl, revUrl, &usedCategory[i].handle ))
      {
         block = 1;   /* found a match ! */
	 break;
      }
   }
   /* optional: for upload of uncategorised URLs: */
   if (UFDBVerifyURLisUncategorised( revUrl ))
      UFDBsaveUncategorisedURL( strippedUrl );
   /* free the internal data structure used by revURL */
   UFDBfreeRevURL( admin, revUrl );

The API also has a set of functions to maintain and upload a list
of uncategorised domain names.  These functions are used to 
improve the quality of the URL database by submitting them to URLfilterDB
for categorisation and inclusion in the next version of the URL database
(see also uncat.c)

Each URL can be checked against all categories of the URL database 
with UFDBVerifyURLisUncategorised().  Note that there is a 'hidden'
category called "checked" that contains domains of previously 
checked-but-not-categorised URLs, e.g. www.fbi.gov is in no category
and always accessible but is included in the checked category to 
prevent unnecessary uploads of URLs that will not be included in 
any category.

HTTPS proxy tunnels can be detected by calling the function
UFDBcheckForHTTPStunnel().  To enable this feature in apitest.c
use "#define UFDB_API_CHECK_PROXY_TUNNELS" in apitest.c
The 3rd parameter of UFDBcheckForHTTPStunnel() is a flag; if it has
the value UFDB_API_ALLOW_QUEUING HTTPS proxy tunnel verifications
are queued and executed by separate verifier threads.
In case that the flag is zero (0), the check is performed immediately
and takes  about 3 seconds to complete.
NOTE: when checks are queued, UFDBcheckForHTTPStunnel() returns
UFDB_API_OK during the first 3 seconds and then after the detection has
completed, the check will return UFDB_API_ERR_TUNNEL.  This implies
that users can use proxy tunnels but only for 3 seconds.

NOTE: UFDBcheckForHTTPStunnel() queues checks if the flag UFDB_API_ALLOW_QUEUING
is used and the implementation requires that 1-8 threads are created by
the application to process the queued proxy tunnel verification requuests.
Hence the applications needs code like this:
   pthread_create( &th1, &attr, UFDBhttpsTunnelVerifier, NULL );
   ...
   pthread_create( &th8, &attr, UFDBhttpsTunnelVerifier, NULL );

Although UFDBVerifyURLisUncategorised() has a high performance,
it is recommended to use this function not too much to keep
an overall good performance of the URL filter.  apitest.c uses
a counter that is used to verify 12% of the URLs.  Because 
a single visit to a website usually involves many URL lookups
it is more than sufficient to check "only 12%".

Finally, UFDBuploadUncategorisedURLs() needs to be called at an 
appropriate time (e.g. just before a new version of the database is
loaded), to upload the collected uncategorised URLs to URLfilterDB.


You may contact the URLfilterDB support desk for more information:
support@urlfilterdb.com

