Using csevalidator.dll

NOTE: This documentation is ongoing. Therefore, this documentation may not be complete or may be inaccurate. It will constantly continue to improve, however. If you believe that there is anything missing or inaccurate, then please contact us.

The functions and their parameters available in csevalidator.dll are specified in the csevalidator.h file that should be included with projects that you create that will use this DLL. csevalidator.h contains a lot of needed information that is not available in this documentation because it is in csevalidator.h. This includes all available functions and their parameters and many constants (#defines) needed to interact with the functions. If you are dynamically linking the DLL and using C/C++, you may also find csefunctionpointerassign.cpp useful.

Download the developer DLL files | Download a 16x16 red H icon that you can use

New Wide String Support in v8.0

Starting with CSE HTML Validator 8.0, strings are now handled internally as wide strings (UTF-16). Therefore, equivalent functions with wide string support are now available in the DLL and should be used whenever possible, although the older non-wide string functions are still available. These wide string functions are just like the non-wide string functions but the function name ends in "W". For example, instead of CSESetString(), use CSESetStringW() whenever possible.

Integrating for Lite/Std/Pro

The integration works very much the same between editions. You can allow your users to switch editions (and/or versions) by allowing them to specify which CSE HTML Validator DLL they want to use, although doing this should not be needed as there will usually only be one version and edition of CSE HTML Validator that the user is using.

We recommend that you design the integration of CSE HTML Validator with your application using the professional edition and linking to the DLL dynamically. To support the lite edition, just use the lite edition DLL instead of the std/pro DLL. You'll get different validation results from the DLL, but the interface to each edition's DLL is the same. Some features may not be supported in the lite edition, and if you call an unsupported function, then the return value may indicate specifically that it is not supported, or it will just appear to work without problems. In any case, all DLL editions are designed to be easily interchangeable.

Pseudo-code

You generally make the validator available to your users in the following manner:

  1. Add a menu option and/or toolbar button to your program that lets the user check their HTML, XHTML, and CSS documents with CSE HTML Validator. This option can be called something like "Check HTML", "Use CSE HTML Validator", or "HTML Validator".
  2. If the user clicks on the menu item or button, then perform the validation if CSE HTML Validator is installed. If it is not installed, then tell the user where they can obtain CSE HTML Validator. You may direct them to our web site so they can download and install it. We do not recommend that you disable the menu item and/or toolbar button if CSE HTML Validator is not installed. Instead, we recommend that you tell the user they need to first download and install CSE HTML Validator.
  3. You can optionally provide additional menu items to open the validator engine options and/or the configuration editor.
  4. You can also provide additional menu items that let the user select a "validation mode". For example, in CSE's editor, a user can select Tools->Validate->Accessibility messages only or Tools->Validate->Errors only. "Accessibility messages only" and "Errors only" are validation modes, also called job subtypes. See using job subtypes pseudo-code.

You generally use the validator in the following manner:

  1. Load the validator DLL with the Windows' function LoadLibrary() like in Instance=LoadLibrary("csevalidator.dll");. After loading the library, obtain function pointers to the validator DLL functions. See finding csevalidator.dll.
  2. Initialize the validator by obtaining a configuration handle with CSEGetHandle() and loading the program configuration and HTML configuration using this handle. When you tell CSE HTML Validator to perform a job, you must give it a configuration handle that it uses to perform the job. This tells the validator how to perform the job with regards to the options that are configurable. It also includes the HTML configuration which tells CSE HTML Validator the syntax rules of the document it is checking. An HTML configuration is required and must be loaded into any configuration handle that will be used to check a document's syntax.
  3. To make CSE HTML Validator do anything useful, it needs a job to do. You first need to get a job handle using CSEGetHandle(). You then set up the job using the job handle and other functions such as CSESetInteger() and CSESetString().
  4. When you have the configuration handle and job handle ready, you can then call CSERunJob() with the configuration and job handles. This function performs the job and passes back a result handle that you can use to obtain the results of the job, usually by calling functions such as the CSEGetInteger() and CSEGetString() functions.

Finding csevalidator.dll:

Before using csevalidator.dll, you must first be able to load it.

In addition to the below, which explains how to find the DLL automatically, consider an option in your program that lets a user specify the exact location of the version and edition of the CSE HTML Validator DLL that he/she would like to use.

General information on using the functions:

Before CSE can perform a job, you must set up a configuration by obtaining at least one configuration handle. How to initialize and obtain a configuration handle:

  1. Obtain a new configuration handle and initialize it by loading the configuration options from the registry by calling CSEGetNewHandle(CSEGETNEWHANDLECFG | CSEGETNEWHANDLEREGISTRYLOAD). The handle returned by this function will be called "confighandle".
  2. If you are checking a document's syntax, then you need to load the HTML configuration. You can do this by calling CSEHTMLConfiguration(NULL, confighandle, CSEHTMLCONFIGURATIONLOAD).

Before performing a job, you must get a job handle and then set-up the job. How to obtain a job handle and set it up:

  1. Simply call CSEGetNewHandle(CSEGETNEWHANDLEJOB). The handle returned by this function will be called "jobhandle".
  2. You must decide 1) what job you want CSE to do, 2) from where the input source is, and 3) any other flags that need to be changed from the default before doing the job.
  3. To tell CSE what job to do, call CSESetInteger(jobhandle, CSEJOBTYPE, jobtype), where jobtype is a CSEJOBTYPExxx define from CSEVALIDATOR.H.
  4. To tell CSE where the job input comes from, call CSESetInteger(jobhandle, CSEJOBSOURCE, jobsource), where jobsource is a CSEJOBSOURCExxx define from CSEVALIDATOR.H. CSEJOBSOURCEBUFFER is the default.
    1. If the source is the job buffer:
      1. You need to load the job buffer. If the job handle has been used before, you should clear it before loading the new job by calling CSESetInteger(jobhandle, CSEJOBRESETBUFFER, 0).
      2. Load the job buffer line by line by adding lines to it. For each line in the input, call CSESetString(jobhandle, CSEJOBADDLINETOBUF, line), where line is a const char * to the line to add.
    2. If the source is from a file:
      1. You need to set the filename from which CSE will load the job buffer. Call CSESetString(jobhandle, CSEJOBINFILENAME, filename).
  5. Tell CSE where the output of the job goes. It can be only to the result buffer or also to a file. If you want CSE to write the output buffer to a file, call CSESetFlag(jobhandle, CSEJOBFLAGS, CSEJOBFLAGOUTPUTTOFILE, 1) and set the filename to write to by calling CSESetString(jobhandle, CSEJOBOUTFILENAME, filename). The default is only to write to the result buffer.
  6. Set any other job flags, integers, or strings that need to be changed for your job.

How to run a job and obtain a results handle:

  1. Once the configuration handle and job handle is ready to go, tell CSE to do the job by calling CSERunJob(NULL, confighandle, jobhandle, 0). If CSE successfully completes the job (excluding minor errors and problems), a result handle, that is 0 or greater, is created and returned. Note that you do not need to pass a result handle to CSERunJob() as it creates on itself. If a serious error occurred preventing the job from running, a negative number is returned that indicates the error and no result handle is created or returned. The handle returned by this function will be called "resulthandle".
  2. Use the result handle obtained from CSERunJob() to get information about the job. For instance, to obtain the message information from a validation job:
    1. Find out how many total messages there are by calling CSEGetInteger(resulthandle, CSERESULTNUMTOTALMESSAGES).
    2. Find out how many messages there are of a certain type (error, warning, message, comment, etc.). For instance, get the number of error messages by calling CSEGetInteger(resulthandle,CSERESULTNUMERRORS). You may also use CSERESULTNUMWARNINGS, CSERESULTNUMMESSAGES, and CSERESULTNUMCOMMENTS.
    3. Use a "for loop" or equivalent to get each message. Note that the first message's index is 1 and not 0. To determine the number of messages, use CSERESULTNUMTOTALMESSAGES (see above).
    4. Example: To get what type of message the third message is, call CSEGetInteger2(resulthandle, CSERESULTMSGTYPE, 3). The return value is the value of a CSEMSGTYPExxx define that indicates if the message is an error, warning, message, or comment.
    5. Example: To get the first message's text, call CSEGetString2(resulthandle, CSERESULTMSGTEXT, 1). To get the second message's text, call CSEGetString2(resulthandle, CSERESULTMSGTEXT, 2).
    6. Example: To get the line (1 based) of the input buffer that caused the fifth message to be generated, call CSEGetInteger(resulthandle, CSERESULTMSGLINELOC, 5).
    7. To get the character location (1 based; the first character on each line is character 1 of the line) of the input buffer line that caused the fifth message to be generated, call CSEGetInteger2EZ(resulthandle, CSERESULTMSGCHARLOC, 5). To get how many characters, call CSEGetInteger2EZ(resulthandle, CSERESULTMSGCHARLOCLENGTH, 5);

Handling handles:

  1. Do not forget that when you are finished with any handle that you should free it by calling CSEFreeHandle(handle, 0).
  2. The same job handle or configuration handle can be used to runs jobs over and over, or you can obtain a new job handle for each new job you want to do. However, it is recommended that you use the same configuration handle for all jobs that you run unless it is required that you need more than one configuration handle.
  3. A new result handle is created every time a job is successfully executed without any major problems. Once the results are no longer needed, you should delete the results handle to free the memory.
  4. To monitor how many handles are open at any one time, call CSEGetNumberOfHandles(0). Use this to monitor your program for memory leaks caused by not freeing handles.

Opening/using the Validator Engine Options:

  1. Call CSEOpenValidatorOptions(hwnd, confighandle, flags). hwnd can be NULL.
  2. flags should be zero or may be set accordingly. For example, set flags to CSEOPENVALOPTIONSAUTOSAVE so that the options are automatically saved (to the registry) unless the user cancels.
  3. Any changes are not saved to the registry if CSEOPENVALOPTIONSAUTOSAVE is not used. In this case, call CSEWriteToRegistry(hwnd, confighandle, 0) to save (to the registry) the current options in memory so that the options can be reloaded the next time that the validator DLL is initialized. You can do this before unloading or freeing the validator DLL or at any time.

Opening/using the HTML Configuration Editor:

  1. Call CSEOpenConfigurationEditor(hwnd, confighandle, 0). hwnd can be NULL.
  2. It is recommended that CSEHTMLConfiguration(hwnd, confighandle, CSEHTMLCONFIGURATIONASKSAVE) is called before unloading or freeing the validator DLL. This will ask the user if he or she wants to save the HTML configuration if it has changed. Using this flag, the return values are:
    • 1 - the user is asked whether to save the configuration and the user chooses to cancel the operation
    • 0 - the HTML configuration is saved (after asking the user) or has not changed
    • negative value - a problem occurred
  3. Other flags available with CSEHTMLConfiguration() are listed in csevalidator.h.

Getting version/edition information