CSS HTML Validator 2019/v19 and later releases are native 64-bit and include 64-bit csevalidator-x64.dll. Version 19.0010 and later also include 32-bit csevalidator.dll for backward compatibility.
Documentation is Ongoing
NOTE: The developer information and documentation is ongoing. If you believe that there is anything missing or inaccurate then please contact us.
Using csevalidator.dll (or csevalidator-x64.dll)
The functions and their parameters available in csevalidator[-x64].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
Strings are now handled internally as wide strings (UTF-16). The wide string functions should be used whenever possible instead of the legacy non-wide string functions. The wide string functions are just like the non-wide string functions but the function name ends in "W". For example, instead of
CSESetStringW() whenever possible.
Integrating with Different Editions (Lite / Home / Pro / Enterprise)
The integration works very much the same among editions. You can allow your users to switch editions (and/or versions) by allowing them to specify which CSS 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 CSS HTML Validator that the user is using.
We recommend that you design the integration of CSS 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 Home/Pro edition 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.
You generally make the validator available to your users in the following manner:
- Add a menu option and/or toolbar button to your program that lets the user check their HTML, XHTML, and CSS documents with CSS HTML Validator. This option can be called something like "Check HTML", "Use CSS HTML Validator", or "HTML Validator".
- If the user clicks on the menu item or button, then perform the validation if CSS HTML Validator is installed. If it is not installed, then tell the user where they can obtain CSS 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 CSS HTML Validator is not installed. Instead, we recommend that you tell the user they need to first download and install CSS HTML Validator.
- You can optionally provide additional menu items to open the validator engine options and/or the configuration editor.
- You can also provide additional menu items that let the user select a "validation mode". For example, in the validator'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:
- Load the validator DLL with the Windows' function
LoadLibrary() like in
Instance=LoadLibrary("c:\\path\\to\\csevalidator.dll")). After loading the library, obtain function pointers to the validator DLL functions. NOTE: To mitigate DLL hijacking risks, always use the full path to the DLL. See finding csevalidator[-x64].dll.
- Initialize the validator by obtaining a configuration handle with
CSEGetHandle() and loading the program configuration and HTML configuration using this handle. When you tell CSS 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 CSS 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.
- To make CSS 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
- 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
Finding csevalidator-x64.dll (or csevalidator.dll):
Before using csevalidator[-x64].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 CSS HTML Validator DLL that he/she would like to use.
- The validator DLL should be somewhere on the users system and available for your use if the user has installed CSE HTML Validator Pro/Std 4.0 or above or CSE HTML Validator Lite 6.52 or above.
- The best way to find the full path to the DLL is to search for these registry keys in order:
- [64-bit std/pro/enterprise] "ValidatorEngineDLLFullPath-x64" in HKEY_CURRENT_USER\Software\AI Internet Solutions\CSE HTML Validator v4
- [32-bit std/pro/enterprise] "ValidatorEngineDLLFullPath" in HKEY_CURRENT_USER\Software\AI Internet Solutions\CSE HTML Validator v4
- [64-bit lite] "ValidatorEngineDLLFullPath-x64" in HKEY_CURRENT_USER\Software\AI Internet Solutions\CSE HTML Validator Lite v6
- [32-bit lite] "ValidatorEngineDLLFullPath" in HKEY_CURRENT_USER\Software\AI Internet Solutions\CSE HTML Validator Lite v6
- If you want to get the installation folder and DLL filename separately, then you can obtain the folder where the DLL is installed and then the DLL filename and then combine them.
- [install folder for std/pro/enterprise] "InstallDir" in HKEY_CURRENT_USER\Software\AI Internet Solutions\CSE HTML Validator v4
- [32-bit DLL filename for std/pro/enterprise] "ValidatorEngineDLL" in HKEY_CURRENT_USER\Software\AI Internet Solutions\CSE HTML Validator v4
- [64-bit DLL filename for std/pro/enterprise] "ValidatorEngineDLL-x64" in HKEY_CURRENT_USER\Software\AI Internet Solutions\CSE HTML Validator v4
- [install folder for lite] "InstallDir" in HKEY_CURRENT_USER\Software\AI Internet Solutions\CSE HTML Validator Lite v6
- [32-bit DLL filename for lite] "ValidatorEngineDLL" in HKEY_CURRENT_USER\Software\AI Internet Solutions\CSE HTML Validator Lite v6
- [64-bit DLL filename for lite] "ValidatorEngineDLL-x64" in HKEY_CURRENT_USER\Software\AI Internet Solutions\CSE HTML Validator Lite v6
- Finally, you may try reading "InstallDir" in HKEY_USERS\.DEFAULT\Software\AI Internet Solutions\CSE HTML Validator v4 (for the non-lite edition) and then "InstallDir"in HKEY_USERS\.DEFAULT\Software\AI Internet Solutions\CSE HTML Validator Lite v6 (for the lite edition).
- NOTE: To mitigate DLL hijacking risks, always use the full path to the DLL. Because of this, loading the DLL without using a full path is no longer recommended. To load the DLL without a full path (not recommended) you can try
Instance=LoadLibrary("csevalidator.dll")). If the return value (Instance) is not 0, then you've successfully accessed the DLL (of the last version and edition of CSS HTML Validator that was installed with administrator privileges) and should not need to perform other methods to try to locate it. This method will normally work if a user has installed a compatible version of CSS HTML Validator on their system. If this fails and the user did install CSS HTML Validator, then the installer may not have has access to install the DLL in the Windows system folder. In this case, the program will be installed, but the DLL may not be easily accessible unless you first find out where it is installed on the user's system (since it will not be installed in the system folder due to access/permission issues). If you cannot load the library with
LoadLibrary() then you may want to stop here (see below for what to do when the library can't be loaded). However, you may optionally choose to try to find the DLL via another method (some suggestions below) and then call
LoadLibrary() again with the full path to the DLL.
- If all other methods of finding the DLL fail, then you may want to ask the user where the csevalidator[-x64].dll file is. Note that this file will be in the folder where CSS HTML Validator is installed to and may be called something like csevalidatorV190[-x64].dll (for 2019/v19 std/pro/enterprise) or csevalidatorliteV180[-x64].dll (for 2018/v18 lite). In all cases it should begin with "csevalidator[-x64]" and end with ".dll". Whatever the name is, at install time the installer tries to place a copy of the DLL file in the system folder that is always named csevalidator[-x64].dll.
- If you can't load the library, then it may not be installed and you can inform the user, telling them how to obtain the program (usually by pointing them to our web site where they can download CSS HTML Validator). You may also want to inform them that if they have already installed CSS HTML Validator, then they may need to reinstall it with administrator privileges so that DLL can be installed in the system folder. You can also inform the user that your program requires CSS HTML Validator for the validation feature.
- For additional security, consider checking the digital signature of the DLL before attempting to load it.
General information on using the functions:
- There are three handle types: a configuration handle, a job handle, and a result handle. The actual value of a valid handle is >=0 (0 is a valid handle).
- Most functions require a handle that can be any of the three types. The program knows which type it is and if it is valid or not.
- Functions that return integers usually return negative numbers to indicate errors.
- Some functions accept a HWND type parameter that may be used to display messages to the user. This value can be NULL.
- To give the validator a file to process, you need a job handle. You then use the job handle to "load" the job buffer line by line by calling
CSESetString() for each line of the input file.
- If you call a function with bad parameters, the program may display an error message to the user indicating the error and what function the error occurred in. It will then generally return a negative integer or NULL value.
Before HTML Validator 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:
- 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".
- 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:
- Simply call
CSEGetNewHandle(CSEGETNEWHANDLEJOB). The handle returned by this function will be called "jobhandle".
- You must decide 1) what job you want the validator 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.
- To tell the validator what job to do, call
CSESetInteger(jobhandle, CSEJOBTYPE, jobtype), where jobtype is a CSEJOBTYPExxx define from csevalidator.h.
- To tell the validator where the job input comes from, call
CSESetInteger(jobhandle, CSEJOBSOURCE, jobsource), where jobsource is a CSEJOBSOURCExxx define from csevalidator.h. CSEJOBSOURCEBUFFER is the default.
- If the source is the job buffer:
- 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).
- 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.
- If the source is from a file:
- You need to set the filename from which CSE will load the job buffer. Call
CSESetString(jobhandle, CSEJOBINFILENAME, filename).
- Tell the validator where the output of the job goes. It can be only to the result buffer or also to a file. If you want the validator 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.
- 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:
- Once the configuration handle and job handle is ready to go, tell the validator to do the job by calling
CSERunJob(NULL, confighandle, jobhandle, 0). If the validator 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".
- Use the result handle obtained from
CSERunJob() to get information about the job. For instance, to obtain the message information from a validation job:
- Find out how many total messages there are by calling
- 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.
- 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).
- 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.
- 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).
- Example: To get the line (1 based) of the input buffer that caused the fifth message to be generated, call
CSEGetInteger(resulthandle, CSERESULTMSGLINELOC, 5).
- 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)
- Do not forget that when you are finished with any handle that you should free it by calling
- 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.
- 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.
- 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:
CSEOpenValidatorOptions(hwnd, confighandle, flags). hwnd can be NULL.
- 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.
- 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:
CSEOpenConfigurationEditor(hwnd, confighandle, 0). hwnd can be NULL.
- 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
- Other flags available with
CSEHTMLConfiguration() are listed in csevalidator.h.
Getting version/edition information
- To get the version, call
CSEGetInteger3EZ(CSEPROGRAMVERSIONINT). This will return the version number*10000. For example, for version 6.5301, it will return 65301 and for 2019/v19.0013, it will return 190013.
- To get the edition (v7.0+ only), first make sure the version is >= 7.0000 by using
CSEGetInteger3EZ(CSEPROGRAMVERSIONINT) >= 70000. If the version is 7.0 or higher, then
CSEGetInteger3EZ(CSEPROGRAMEDITION) may be used to get the edition. It will return 1 for the professional edition, 2 for the standard edition, or 3 for the lite edition.