Copyright (C)2000-2004 AI Internet Solutions

Created October 26, 2004
Updated October 26, 2004

This C pseudo-code will help you use the CSE HTML Validator DLL for link checking.

This document assumes that you have already loaded the validator DLL and have access to the DLL functions. To enable the link status CSELINKSTATUSMAYBEOK (recommended), do this once after loading the DLL:
CSESetFlag2(CSECFGGLOBALFLAGS, CSEGLOBALFLAGENABLELINKMAYBEOK, 1);

To use the link checker, a list of links must be loaded into the validator. When the links are loaded, tell the DLL to check the links. You'll then need to get the results of the link check.

Normally you will want to load the link checker with a list of links extracted from a document. When an HTML document is validated with the included configuration file, the links are placed into a variable array. You can read that array to get the links.

Example:

Assume that you have a resulthandle variable from a validation, containing the results of the validation.

// get the links that the validator extracted from the document during the validation
// these links are stored in the arrays "links" and "linkstype"
// the "links" array contains the actual link
// the "linkstype" array contains information about where the link was extracted, like "A HREF" or "IMG SRC"
int linksindex, linkstypesindex;

linksindex=CSEGetInteger4EZ(resulthandle, CSERESULTSYMBOLNAMEINDEX, "links");
linkstypesindex=CSEGetInteger4EZ(resulthandle, CSERESULTSYMBOLNAMEINDEX, "linkstypes");

int numlinks; // number of links

// get the number of links (entries in array "links")
if (linksindex>=0) numlinks=CSEGetInteger2EZ(resulthandle, CSERESULTNUMSYMBOLVALUES, linksindex);
else numlinks=0;

// now store the links somewhere
const char *link, *linktype;
for (int i=0; i<numlinks; i++) {
 link=CSEGetString4(resulthandle, CSERESULTSYMBOLVALUE, linksindex, i);
 linktype=CSEGetString4(resulthandle, CSERESULTSYMBOLVALUE, linkstypesindex, i);
 // now store a copy of link and linktype character pointers in your own array before getting the next link
}

When you have a list of links to check, you'll then need to load them into the DLL. The links should be absolute links, starting with http:// or being a local file link with full path information like "c:\html\index.html". They can also be mailto links like "mailto:test@domain.com".

// assume numlinks is the number of links you are loading into the DLL
int linkindex;
for (int i=0; i<numlinks; i++) {
 // set link to the absolute link to load into the DLL - any original character references such as character entities in the link should not have been converted
 linkindex=CSESetString3(CSEADDABSOLUTELINKNOENT, link); // if the link is already in the validator, then returns the index to the existing link, otherwise returns the index to the newly added link
 if (linkindex>0) { // if link added successfully
  // set the user agent string to use when checking the link - here it's set to "CSE HTML Validator"
  CSESetString7(CSELINKAGENT, linkindex, "CSE HTML Validator");
  if (using a username and password) {
   CSESetString7(CSELINKUSERNAME, linkindex, username); // set username to use when checking link
   CSESetString7(CSELINKPASSWORD, linkindex, password); // set password to use when checking link
  }
  else
   CSESetString7(CSELINKUSERNAME, linkindex, ""); // disable username and password when checking the link
  }
 }
}

When the list of absolute links is loaded into the validator, the link check can be done

if (CSEGetInteger3EZ(CSELINKCHECKINGTHREADS)==0) { // if link check not already running
 int jobhandle=CSEGetNewHandle(CSEGETNEWHANDLEJOB); // get a new job handle
 if (jobhandle<0) return; // error if jobhandle is less than 0 so return

 // NOTE: The jobhandle of a CSEJOBTYPECHECKLINKS type job is automatically freed when done, so do not free it
 if (CSESetInteger(jobhandle, CSEJOBTYPE, CSEJOBTYPECHECKLINKS)<0) return; // set the jobtype - error if fuction returns less than 0 so return

 // if you want the link checker to send messages to your application with the progress of the link check, do the following to add lines to the job buffer with CSEJOBADDLINETOBUF
 // windowhandle is the handle of the window, converted to a text string, to send the status messages to
 if (CSESetString(jobhandle, CSEJOBADDLINETOBUF, windowhandle)) return retval;
 // windowmessage is the message to send to the window (CSE uses WM_APP+1)
 // the LPARAM of the message will be a pointer to a global atom containg a text string (created with GlobalAddAtom())
 // messages will be sent approximately after every 5% increment in progress
 // a global atom containing "-LinkCheckMessage x" will be sent, where x is an integer (0-100) indicating the link check percentage complete, the WPARAM of the message will be an integer (0-100) also indicating the percentage complete
 // when the link checker is completely finished, the global atom will contain "-LinkCheckMessage 101" and the WPARAM argument of the message will be 101
 // it is the responsibility of the code receiving the message to free the global atom after you have read it
 if (SetString(jobhandle, CSEJOBADDLINETOBUF, windowmessage)) return retval;

 // now start the link checking
 if (CSERunJob(Handle, p->vol->valconfig, jobhandle, 0)<0) return retval;
}

When the link checking is done, the status of the links can now be obtained. You can try to obtain the status of links before the link checker has completed, but not all links will be checked.

If you'd like, you can verify that the link checker has completed
if (CSEGetInteger3EZ(CSELINKCHECKINGTHREADS)==0) { // if link checker has completed and is not currently checking any links
 // do something here when the link checker is not running
}

// assume numlinks is the number of links in your link array that you want the result for
// linkstatusint should return one of the following if the link is found (or <0 if not found)
//  CSELINKSTATUSOK - link is OK
//  CSELINKSTATUSNOTOK - link is not OK (bad)
//  CSELINKSTATUSNOTCHECKED - link has not been checked yet
//  CSELINKSTATUSMAYBEOK - link might be OK or might be bad (usually displayed as a warning link in CSE) redirected links are links that can be considered "maybe OK"
int linkstatusint;
const char *linkstatusstring, *linkcommentstring;
for (int i=0; i<numlinks; i++) {
 // link is a character pointer set to the link you want the results for - set link according to loop variable i here
 linkstatusint=CSEGetInteger5EZ(CSELINKSTATUSINT2NOENT, link); // CSELINKSTATUSOK, CSELINKSTATUSNOTOK, etc.; <0 if link not found
 linkstatusstring=CSEGetString5(CSELINKSTATUSSTRING, link); // a string describing the status to display to user; NULL if link not found
 linkcommentstring=CSEGetString5(CSELINKCOMMENTSTRING, link); // a comment to display to user; NULL if link not found
}