HTML Athlete SDK

About this document

This document serves as a full documentation of HTML Athlete SDK. First you get a brief general overview, in which all assets will be summarized. Then these assets will be described in detail.

Brief overview

Constants

Types

Functions

Predefined constants

ATH_BEHAVIOUR_BLOCK

Availability

HTML Athlete SDK 0.1

Describtion

Orders the caller to block while compression is in progress. This type of behaviour is set in default. See the ATHSetCallerBehaviour function for further information.

ATH_BEHAVIOUR_DONT_BLOCK

Availability

HTML Athlete SDK 0.1

Describtion

Orders the caller not to block while compression is in progress. See the ATHSetCallerBehaviour function for further information.

ATH_BEHAVIOUR_NOTIFY_SENDING_A_MESSAGE

Availability

HTML Athlete SDK 0.1

Describtion

Orders the caller to wait for a message specified in the ATHTCompressionDoneMessage structure. See the ATHSetCallerBehaviour function for further information.

ATH_CONTENT_TYPE_CSS

Availability

HTML Athlete SDK 0.1

Describtion

Specifies, that the input contains correct Cascade Style Sheet document.

Note

In the case the document is not correct, you can not expect a correct functionality of compression routines. For instance, when the document contains a non-ended multiline comment, the routine may be broken down because of unexpected content error.

ATH_CONTENT_TYPE_HTML

Availability

HTML Athlete SDK 0.1

Describtion

Specifies, that the input contains correct HTML document.

Note

In the case the document is not correct, you can not expect a correct functionality of compression routines. For instance, when the document contains a non-ended multiline comment, the routine may be broken down because of unexpected content error.

ATH_CONTENT_TYPE_JS

Availability

HTML Athlete SDK 0.1

Describtion

Specifies, that the input contains correct ECMAScript-based document (JScript/JavaScript).

Note

In the case the document is not correct, you can not expect a correct functionality of compression routines. For instance, when the document contains a non-ended multiline comment, the routine may be broken down because of unexpected content error.

ATH_LANGUAGE_CESKY

Availability

HTML Athlete SDK 0.2

Describtion

Indicates that the instance should be transformed into czech language mutation.

ATH_LANGUAGE_DEUTSCH

Availability

HTML Athlete SDK 0.3

Describtion

Indicates that the instance should be transformed into german language mutation.

ATH_LANGUAGE_ENGLISH

Availability

HTML Athlete SDK 0.2

Describtion

Indicates that the instance should be transformed into english language mutation, which is the default setting when creating a new instance.

ATH_PADDING_LEFT

Availability

HTML Athlete SDK 0.1

Describtion

Defines the neccessary memory left padding of the document (of any supported kind). See the ATHCompressRawData function for further information.

ATH_PADDING_RIGHT

Availability

HTML Athlete SDK 0.1

Describtion

Defines the neccessary memory right padding of the document (of any supported kind). See the ATHCompressRawData function for further information.

ATH_PROPERTY_BEEP_WHEN_FINISHED

Availability

HTML Athlete SDK 0.1

Describtion

Enables or disables (according the value set in the ATHSetProperty function) the beep at the end of document compression. Setting this property to false the compression routine does not beep signaling the compression was finished successfully. This property is in default set to true.

ATH_PROPERTY_CSS_COMPRESSION_ENABLED

Availability

HTML Athlete SDK 0.1

Describtion

Enables or disables (according the value set in the ATHSetProperty function) the Cascade Sheets compression routine. Having it disabled while compression, all CSS fragments will be copied as they are to the output. This property is in default set to false.

ATH_PROPERTY_DELETE_HTML_COMMENTS

Availability

HTML Athlete SDK 0.1

Describtion

Enables or disables (according the value set in the ATHSetProperty function) the HTML comments blanking. Having it disabled while compression, all HTML comments will be copied as they are to the output. This property is in default set to false.

ATH_PROPERTY_HIDE_JS_IN_OLDER_BROWSERS

Availability

HTML Athlete SDK 0.1

Describtion

Enables or disables (according the value set in the ATHSetProperty function) the leaving or blanking of hiding of unsupported contents in older web browser versions. As the hiding command there is ment the "" pair. This property is in default set to false.

Example

Keep this property set to true in order to view the following web page even after compression in Internet Explorer 1.0 properly.

<html><body>
	<script language=javascript><!--
		function Welcome(){/*...*/}
	//--></script>
	Welcome to my homepage.
</body></html>

ATH_PROPERTY_JS_COMPRESSION_ENABLED

Availability

HTML Athlete SDK 0.1

Describtion

Enables or disables (according the value set in the ATHSetProperty function) the JavaScript compression routine. Having it disabled while compression, all JS fragments will be copied as they are to the output. This property is in default set to false.

ATH_PROPERTY_PROTECT_EVENTS

Availability

HTML Athlete SDK 0.1

Describtion

Enables or disables (according the value set in the ATHSetProperty function) the HTML event protection. Having it enabled, all events (like onmousemove or onload) will be kept with quotas around their values (only if the quotas are already present in the original, i.e. in the input document). When problems occur while viewing the compressed web page, try to disable this property (set it to true). This property is in default set to true.

ATH_RESULT_BUSY

Availability

HTML Athlete SDK 0.1

Describtion

Informs the caller, that the worker thread is not ready to receive its commands. Obviously this return code is obtained while compressing the document.

ATH_RESULT_CAN_NOT_READ_FILE

Availability

HTML Athlete SDK 0.1

Describtion

The specified file can not be read or does not exist at all. Check the file path in order to ensure, it is correct.

Note

On Windows 9x/Me the string must not exceed MAX_PATH characters. For more information, see Naming a File on the MSDN portal.

ATH_RESULT_CAN_NOT_WRITE_FILE

Availability

HTML Athlete SDK 0.1

Describtion

The compressed document could not be written to the specified file. Check the file path in order to ensure, it is correct.

Note

On Windows 9x/Me the string must not exceed MAX_PATH characters. For more information, see Naming a File on the MSDN portal.

ATH_RESULT_CANCEL

Availability

HTML Athlete SDK 0.2

Describtion

The dialogue was closed up negative wise (i.e. either the Escape or the Cancel button was pressed).

ATH_RESULT_ERROR_CREATING_AN_INSTANCE

Availability

HTML Athlete SDK 0.1

Describtion

An error arose while attempting to create a new HTML Athlete instance. Try to free a bit of memory and then try again.

ATH_RESULT_GENERAL_COMPRESSION_ERROR

Availability

HTML Athlete SDK 0.1

Describtion

An unknown error arose while attempting to compress the document. This error certainly occurs when the input document contains fatal errors, among which one can range the un-ended comment, for instance. Please try to ensure that your web page (when you wrote it in hand) is as errorless as possible!

ATH_RESULT_IDLE

Availability

HTML Athlete SDK 0.1

Describtion

Informs the caller, that the worker thread is idle. For instance, this return code is obtained when trying to take chars of the document compressed so far.

ATH_RESULT_OK

Availability

HTML Athlete SDK 0.1

Describtion

Returned when function call succeedes or when a dialog is positively closed up (i.e. by pressing the OK).

ATH_RESULT_STILL_UNAUTHORIZED

Availability

HTML Athlete SDK 0.1

Describtion

This return code informs the caller that the specified instance has not been authorized yet, or that the authorization failed.

Recommendation

It is highly recommended rather to copy the obtained authorization code from the mail than trying it to put down character by character per hand into your application source code.

ATH_RESULT_UNKNOWN_BEHAVIOUR

Availability

HTML Athlete SDK 0.1

Describtion

The specified caller behaviour was not recognized and therefore could not be set. The prime caller behaviour is maintained by the instance.

ATH_RESULT_UNKNOWN_CONTENT_TYPE

Availability

HTML Athlete SDK 0.1

Describtion

The specified content type was not recognized and therefore could not be set.

ATH_RESULT_UNKNOWN_INSTANCE

Availability

HTML Athlete SDK 0.1

Describtion

The specified instance was not found. Please check whether you do not destroy the instance before you pass it in another HTML Athlete's function as parameter.

ATH_RESULT_UNKNOWN_LANGUAGE

Availability

HTML Athlete SDK 0.2

Describtion

The specified language does not exist. Please see the ATH_LANGUAGE_* constants to elicit which languages are currently available.

ATH_RESULT_UNKNOWN_PROPERTY

Availability

HTML Athlete SDK 0.1

Describtion

The specified instance's property does not exist and therefore could not be changed. The failure does not affect any of instance's legal properties.

ATH_RESULT_UNKNOWN_THREAD_PRIORITY

Availability

HTML Athlete SDK 0.1

Describtion

The specified thread priority is not a legal Windows thread priority. Please refer the ATHSetWorkerThreadPriority function for further information.

Predefined variable types

ATHBehaviour

Availability

HTML Athlete SDK 0.1

Describtion

Function parameter of this type expects a caller behaviour constant to be put in. In this case, ATH_BEHAVIOUR_* constants come in play.

ATHContentType

Availability

HTML Athlete SDK 0.1

Describtion

Function parameter of this type expects a document content type specification to be put in. In this case, all ATH_CONTENT_TYPE_* constants are relevant.

ATHInstance

Availability

HTML Athlete SDK 0.1

Describtion

Function parameter of this type expects a HTML Athlete's instance handler to be put in. See the tutorial to get familiar with instances.

ATHLanguage

Availability

HTML Athlete SDK 0.2

Describtion

Function parameter of this type expects a language specifier to be put in. In this case, ATH_LANGUAGE_* constants are expected.

ATHPCompressionDoneMessage

Availability

HTML Athlete SDK 0.1

Describtion

Function parameter of this type expects a pointer to the ATHTCompressionDoneMessage structure to be put in. Click the link for further information.

ATHProperty

Availability

HTML Athlete SDK 0.1

Describtion

Function parameter of this type expects a property identifier to be put in. In this case, all ATH_PROPERTY_* constants are relevant.

ATHPropertyValue

Availability

HTML Athlete SDK 0.1

Describtion

Function parameter of this type expects a property value to be put in. In this case, ATHPropertyValue type is defined as boolean, therefore true, or false are the only relevant values expected.

ATHResult

Availability

HTML Athlete SDK 0.1

Describtion

Every HTML Athlete function returns a value of this type. Returning a value the function tries to inform about the inner state. In this case, all ATH_RESULT_* constants are relevant. For instance, when everything goes right, the function returns ATH_RESULT_OK code.

ATHTCompressionDoneMessage

Availability

HTML Athlete SDK 0.1

Definition

struct {
	HWND window;
	uint messageId;
} ATHTCompressionDoneMessage;

Describtion

Function parameter of this type informs the function about window which is responsible for receiving the "Compression Done" message. This message is sent when caller behaviour is set to ATH_BEHAVIOUR_NOTIFY_SENDING_A_MESSAGE and compression is done (we do not explicitly say that the compression must be successful in order this message to be sent). For further information see the ATHSetCallerBehaviour function.

Functions

ATHAuthorizeInstance

Availability

HTML Athlete SDK 0.1

Prototype

ATHResult ATHAuthorizeInstance (
	ATHInstance instance,
	char *authKey,
	char *authCode
)

Parameters

Describtion

The function tries to authorize the specified instance. Authorization is required because of two reasons:

When the instance is not authorized or the authorization has expiried, a message box appears informing you that you should authorize again or download the newest (and more errorless) version of HTML Athlete SDK. When this is the case, please visit HTML Athlete SDK's home page (see Contact on the index page).

Possible return codes

ATH_RESULT_OK, ATH_RESULT_UNKNOWN_INSTANCE, ATH_RESULT_BUSY, ATH_RESULT_STILL_UNAUTHORIZED

ATHCompressFile

Availability

HTML Athlete SDK 0.1

Prototype

ATHResult ATHCompressFile (
	ATHInstance instance,
	ATHContentType contentType, 
	pchar *fileName
)

Parameters

Describtion

This top-level function does three thinks:

Note, that calling this function the caller behaves always blocking no matter what behaviour is set to the specified instance.

Possible return codes

ATH_RESULT_OK, ATH_RESULT_UNKNOWN_INSTANCE, ATH_RESULT_CAN_NOT_READ_FILE, ATH_RESULT_CAN_NOT_WRITE_FILE, ATH_RESULT_BUSY, ATH_RESULT_GENERAL_COMPRESSION_ERROR

ATHCompressRawData

Availability

HTML Athlete SDK 0.1

Prototype

ATHResult ATHCompressRawData (
	ATHInstance instance,
	ATHContentType contentType,
	char *content,
	char **endOfContent,
	void *params
)

Parameters

Describtion

This low-level function tries to compress the content specified by its first character (content). When it succeeds, the endOfContent points to the first character after the compressed content, which is obviously the zero character (0x00).

Let's make two essential notes:

Possible return codes

ATH_RESULT_OK, ATH_RESULT_UNKNOWN_INSTANCE, ATH_RESULT_BUSY, ATH_RESULT_UNKNOWN_CONTENT_TYPE, ATH_RESULT_UNKNOWN_INSTANCE, ATH_RESULT_GENERAL_COMPRESSION_ERROR

ATHCreateInstance

Availability

HTML Athlete SDK 0.1

Prototype

ATHResult ATHCreateInstance (
	ATHInstance *instance
)

Parameters

Describtion

The function attempts to create the new HTML Athlete instance. When circumstances are set so it can not succeed, it returns the ATH_RESULT_ERROR_CREATING_AN_INSTANCE error code. However during intensive testing of this SDK, the function never returned it (maybe because of always enough of free memory was available). For a simple example how to create and manage instance see the starting tutorial of this SDK.

Newly created instance has its properties set to default. These defaults are (stated in brackets):

Possible return codes

ATH_RESULT_OK, ATH_RESULT_ERROR_CREATING_AN_INSTANCE

ATHDestroyInstance

Availability

HTML Athlete SDK 0.1

Prototype

ATHResult ATHDestroyInstance (
	ATHInstance instance
)

Parameters

Describtion

The function attempts to destroy an existing HTML Athlete instance. When wrong or no longer relevant handler is passed as instance parameter, the function fails and returns ATH_RESULT_UNKNOWN_INSTANCE error code.

Possible return codes

ATH_RESULT_OK, ATH_RESULT_UNKNOWN_INSTANCE, ATH_RESULT_BUSY

ATHGetCharsProcessed

Availability

HTML Athlete SDK 0.1

Prototype

ATHResult ATHGetCharsProcessed (
	ATHInstance instance,
	int *charsProcessed
)

Parameters

Describtion

The function attempts to obtain the characters processed during a compression process so far. Obviously, to make use of this function you must set the caller thread behaviour to non-blocking one when calling any of compression functions, or having another parallel thread created, which serves for pediodical sampling of characters processed. However, when the instance's worker thread is idle (not compressing), the ATH_RESULT_IDLE error code is returned.

Possible return codes

ATH_RESULT_OK, ATH_RESULT_UNKNOWN_INSTANCE, ATH_RESULT_IDLE

ATHGetVersion

Availability

HTML Athlete SDK 0.1

Prototype

int ATHGetVersion (
)

Parameters

Describtion

This function returns HTML Athlete SDK's version.

Possible return codes

This function does not return any error codes, it always succedes. Instead, it returns the double-word with HTML Athlete SDK's version record where on the highest byte, there is recorded the main version and on the second highest byte, there is located the subversion. Other two bytes of returned double-word are unused and set to zero.

ATHShowAboutDialogue

Availability

HTML Athlete SDK 0.2

Prototype

ATHResult ATHShowAboutDialogue (
	ATHInstance instance,
	HWND parentWnd
)

Parameters

Describtion

This function invokes the HTML Athlete's standard About dialogue for the instance specified by instance parameter. The dialog shown is always modal, which means the caller thread is suspended until the dialog is closed (the Close button).

Possible return codes

ATH_RESULT_OK, ATH_RESULT_UNKNOWN_INSTANCE

ATHShowSettingDialogue

Availability

HTML Athlete SDK 0.2

Prototype

ATHResult ATHShowSettingDialogue (
	ATHInstance instance,
	HWND parentWnd
)

Parameters

Describtion

This function invokes the HTML Athlete's standard setting dialogue for the instance specified by instance parameter and sets up the controls in order to reflect the instance's state. The shown dialog is always modal, which means the caller thread is suspended until the dialog is closed (in any of two possible ways - either confirming the current setting (the OK button), or refusing them (the Cancel button)).

On this dialogue, there are shown only essential and most safe instance properties - safe in meaning of Windows safety - for example, you can not change the worker thread priority. Such privileges are granted only to the programmers employing the HTML Athlete in their applications. To be able to set up all of the properties you must create and manage your own dialogue.

Possible return codes

ATH_RESULT_OK, ATH_RESULT_UNKNOWN_INSTANCE, ATH_RESULT_BUSY, ATH_RESULT_CANCEL

ATHSetCallerBehaviour

Availability

HTML Athlete SDK 0.1

Prototype

ATHResult ATHSetCallerBehaviour (
	ATHInstance instance,
	ATHBehaviour behaviour,
	void *params
)

Parameters

Describtion

Tries to change the caller thread behaviour during a compression process. In this case, the caller thread is the thread triggering the compression (the callee is the instance's worker thread).

Behaviours available:

Possible return codes

ATH_RESULT_OK, ATH_RESULT_UNKNOWN_INSTANCE, ATH_RESULT_BUSY, ATH_RESULT_UNKNOWN_BEHAVIOUR

ATHSetLanguage

Availability

HTML Athlete SDK 0.2

Prototype

ATHResult ATHSetLanguage (
	ATHInstance instance,
	ATHLanguage language,
)

Parameters

Describtion

Tries to change the instance's language mutation. When the function can not recognize the given language, it fails and returns the ATH_RESULT_UNKNOWN_LANGUAGE constant.

Possible return codes

ATH_RESULT_OK, ATH_RESULT_UNKNOWN_INSTANCE, ATH_RESULT_BUSY, ATH_RESULT_UNKNOWN_LANGUAGE

ATHSetProperty

Availability

HTML Athlete SDK 0.1

Prototype

ATHResult ATHSetProperty (
	ATHInstance instance,
	ATHProperty properties,
	ATHPropertyValue value
)

Parameters

Describtion

The function tries to change the specified properties to the given value. When the function can not recognize though one of the properties, it returns the ATH_RESULT_UNKNOWN_PROPERTY error code.

Instance properties currently available (here enabled means set to true):

Possible return codes

ATH_RESULT_OK, ATH_RESULT_UNKNOWN_INSTANCE, ATH_RESULT_BUSY, ATH_RESULT_UNKNOWN_PROPERTY

ATHSetWorkerThreadPriority

Availability

HTML Athlete SDK 0.1

Prototype

ATHResult ATHSetWorkerThreadPriority (
	ATHInstance instance,
	int priority
)

Parameters

Describtion

The function tries to change the instance's worker thread priority to the specified one. When incorrect thread priority is passed, the function returns the ATH_RESULT_UNKNOWN_THREAD_PRIORITY error code. Look at the MSDN portal for which thread priorities are available before using this function.

Possible return codes

ATH_RESULT_OK, ATH_RESULT_UNKNOWN_INSTANCE, ATH_RESULT_UNKNOWN_THREAD_PRIORITY

EOF