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.
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.
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 CSE HTML Validator. This option can be called something like "Check HTML", "Use CSE HTML Validator", or "HTML Validator".
- 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.
- 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 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:
- 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.
- 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.
- 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().
- 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.
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.
- 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 first thing to try is Instance=LoadLibrary("csevalidator.dll"). If the return value (Instance) is not null, then you've successfully accessed the DLL (of the last version and edition of CSE 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 CSE HTML Validator on their system. If this fails and the user did install CSE 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 Instance=LoadLibrary("csevalidator.dll"), 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.
- To obtain the folder where the DLL is installed in, you can try reading the "InstallDir" registry value in "HKEY_CURRENT_USER\Software\AI Internet Solutions\CSE HTML Validator v4", which should exist if the user has a compatible version (other than the lite edition) installed. If that fails then you can try reading the "InstallDir" registry value in "HKEY_CURRENT_USER\Software\AI Internet Solutions\CSE HTML Validator Lite v6", which should exist if the user has the lite edition installed. The value data of "InstallDir" is a string with the folder that CSE HTML Validator is installed in, like "C:\Program Files\HTMLValidatorLite110". You can search that folder for a DLL file beginning with "csevalidator". I'm not sure if this will work, but you could try something like Instance=LoadLibrary("C:\Program Files\HTMLValidatorLite110\csevalidator*.dll"), using the folder obtained from "InstallDir".
- 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).
- If all other methods of finding the DLL fail, then you may want to ask the user where the csevalidator.dll file is. Note that this file will be in the folder where CSE HTML Validator is installed to and may be called something like csevalidatorV110.dll (for v11 std/pro/enterprise) or csevalidatorliteV110.dll (for v11 lite). In all cases it should begin with "csevalidator" 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.dll. This is why it is recommended that you try Instance=LoadLibrary("csevalidator.dll") first.
- 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 CSE HTML Validator). You may also want to inform them that if they have already installed CSE 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 CSE HTML Validator for the validation feature.
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. CSE 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, CSE 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 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:
- 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 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.
- To tell CSE what job to do, call CSESetInteger(jobhandle, CSEJOBTYPE, jobtype), where jobtype is a CSEJOBTYPExxx define from CSEVALIDATOR.H.
- 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.
- 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 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.
- 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 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".
- 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 CSEGetInteger(resulthandle, CSERESULTNUMTOTALMESSAGES).
- 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 CSEFreeHandle(handle, 0).
- 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:
- Call 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:
- Call 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.
- 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.