/************************************************************************/
Copyright (C)2000-2013 AI Internet Solutions
Last Update: February 14, 2013

2008-05-04: Updated to use wide strings (v8.0 and above). For the old "ANSI" version, see
http://www.htmlvalidator.com/htmlval/developerdllpseudocodeANSI.txt
/************************************************************************/

This C pseudo-code may help you use the CSE HTML Validator DLL when validating a document.

NOTE: If you are loading the DLL dynamically (recommended), be sure to define CSE_USE_DYNAMIC_DLL before including csevalidator.h and when compiling csefunctionpointerassign.cpp.

NOTE: It is suggested that you use these global defines: CSELATESTVERSION and CSE_USE_DYNAMIC_DLL
For example, if compiling with Microsoft's "cl" compiler, then use these compiler options: /DCSELATESTVERSION /DCSE_USE_DYNAMIC_DLL

The defines are in csevalidator.h, so you will need this line in each source file that calls CSE DLL functions:
#define CSE_USE_DYNAMIC_DLL
#include "csevalidator.h"

NOTE: CSE HTML Validator v8.0 and above uses wide strings (wchar_t *) to store and process strings internally. If possible, it is best to use the wide string functions instead.
The wide string functions work like the char * functions but end in "W" and take (and return) wchar_t * parameters instead of char * parameters.
Example: CSEGetString2W() instead of CSEGetString2().
Using the non-wide string functions causes conversions to be done to and from wide strings, which slows things down and introduces conversion limitations.

Load the DLL dynamically
HINSTANCE Instance=LoadLibrary("csevalidator.dll");

You will have to assign the function pointers defined in csevalidator.h. Use the function CSEInitializeDLLPointers() in csefunctionpointerassign.cpp to do this:
CSEInitializeDLLPointers(Instance);

/************************************************************************/
Before using CSE HTML Validator to validate a document:
/************************************************************************/

1. Obtain a configuration handle.

int confighandle=CSEGetNewHandle(CSEGETNEWHANDLECFG|CSEGETNEWHANDLEREGISTRYLOAD);

2. Load the HTML Configuration.

CSEHTMLConfiguration(NULL, confighandle, CSEHTMLCONFIGURATIONLOADDEFAULT);


/************************************************************************/
To validate a document:
/************************************************************************/

1. You need to set up a job. First, get a new job handle then set up the job.

int jobhandle=CSEGetNewHandle(CSEGETNEWHANDLEJOB);

// set the job as a validation type job (CSEJOBTYPEVALIDATE)
// set to CSEJOBTYPESTYLESHEETCHECK to check an external CSS style sheet
// if set to CSEJOBTYPEVALIDATE and the source looks like a style sheet, then the job is automatically changed to CSEJOBTYPESTYLESHEETCHECK
CSESetInteger(jobhandle, CSEJOBTYPE, CSEJOBTYPEVALIDATE); 

// clear the current job buffer (always a good idea)
CSESetInteger(jobhandle, CSEJOBRESETBUFFER, 0);
// in this example, we don't want the output to go to a file
CSESetFlag(jobhandle, CSEJOBFLAGS, CSEJOBFLAGOUTPUTTOFILE, 0);

2a. Assume the source of the job is the job buffer. Therefore, you will need load the job buffer a line at a time (or see 2b). Each line that you load is a line in the source HTML document.

// load the HTML document into the job buffer

// pointer to the line that you are loading into the job buffer
const wchar_t *line;

// numlines is the number of lines in the HTML document
// note: the string pointed to by line is copied to a new memory location so that the memory pointed to by line can be freed or reused after calling CSESetStringW()
// line should not contain newline or return characters (\n or \r)
for (int i=0; i<numlines; i++) {
 point the line parameter to the line to load into the job buffer;
 CSESetStringW(jobhandle, CSEJOBADDLINETOBUF, line);
}

2b. Instead of 2a, you can specify a filename for the source document. To do this, do the following instead of 2a:

// use a filename for the source document
CSESetInteger(jobhandle, CSEJOBSOURCE, CSEJOBSOURCEFILENAME);

// specify the filename, filename should be something like "C:\\files\\document.html"
CSESetStringW(jobhandle, CSEJOBINFILENAME, filename);

2c. Optional settings

// set to the code page of the original source (by string like "utf-8") if available (new v8.9911); returns 0 and does not change anything if the string is not recognized as a charset else sets code page and returns 1, auto-sets CSEJOBFLAGSOURCEISUNICODE flag
CSESetStringW(jobhandle, CSEJOBSOURCECODEPAGEBYSTRING, charset);

/************************************************************************/
To perform the job:
/************************************************************************/

1. Run the job!

// resulthandle should be 0 or greater or an error has occurred
int resulthandle=CSERunJob(NULL, confighandle, jobhandle, 0);

// Check to make sure you have a valid resulthandle:
if (resulthandle<0) { /* handle a failed validation here */ }

Now we have a result handle from which we can pull the results of the job. To get the results of the job:

// get how many messages the validator generated
int nummessages=CSEGetIntegerEZ(resulthandle, CSERESULTNUMTOTALMESSAGES);

// a pointer to the text of the message
const wchar_t *msgtext;
// msg type is CSEMSGTYPEERROR, CSEMSGTYPEWARNING, CSEMSGTYPECOMMENT, or CSEMSGTYPEMESSAGE
int msgtype;
// msgline is 1 based; the first line is line 1, not line 0
int msgline;
// msgchar is 1 based; the first character of each line is char 1, not char 0; -1 if not available
int msgchar;
// msgcharlength is the number of characters starting at msgchar; -1 if not available
int msgcharlength;
// additional information about the message (example: if it is a CSS message, msgflags&CSEMSGFLAGSTYLEMSG will be >0)
int msgflags;
// message ID (if available) - CSE v5.50+ only; <1 if ID is not available
int msgid;

// loop through each message
for (int i=0;i<nummessages;i++) {
 // get the text of the message, first message is 1, not 0, so use i+1
 msgtext=CSEGetString2W(resulthandle, CSERESULTMSGTEXT, i+1);
 msgtype=CSEGetInteger2EZ(resulthandle, CSERESULTMSGTYPE, i+1); // CSEMSGTYPEERROR, CSEMSGTYPEWARNING, CSEMSGTYPECOMMENT, CSEMSGTYPEMESSAGE
 msgline=CSEGetInteger2EZ(resulthandle, CSERESULTMSGLINELOC, i+1);
 msgchar=CSEGetInteger2EZ(resulthandle, CSERESULTMSGCHARLOC, i+1);
 msgcharlength=CSEGetInteger2EZ(resulthandle, CSERESULTMSGCHARLOCLENGTH, i+1);
 msgflags=CSEGetInteger2EZ(resulthandle, CSERESULTMSGMSGFLAGS, i+1);
 if (CSEGetInteger3EZ(CSEPROGRAMVERSIONINT)>=54930) { // supported by v5.4930+
  msgid=CSEGetInteger2EZ(valresults, CSERESULTMSGID, i+1); // CSE v5.50+ only
 }
 else {
  msgid=-1;
 }
 
 // now do something with this information, e.g. save it, display it, etc.
 do something;
}

If you want to display the source HTML/CSS (or read it back):
const wchar_t *line;
line=CSEGetString2W(jobhandle, CSEJOBBUFFERLINE, linenum); // linenum is zero based

/************************************************************************/
To clean up:
/************************************************************************/

1. You should free jobhandle and resulthandle when you don't need them anymore.

CSEFreeHandle(jobhandle, 0);
CSEFreeHandle(resulthandle, 0);

You should also free confighandle when you are finished with that as well. Normally if you are validating multiple documents you will not want to create and free a configuration handle for each document. You should instead use the same configuration handle. When you are finished with the DLL, you should then free it.

// usually done when completely finished with the CSE DLL and your application is terminating
CSEFreeHandle(confighandle, 0);
// unload the DLL
FreeLibrary(Instance);