W3C Reference Library Release Notes

# Library 4.0 Release Notes

Thanks to all the good work done by the alpha testers:

- BROOKS, Charlie
- CONNOR, Kevin
- DOMINGUEZ, Mario J.
- FARKAS, Ivan
- FLEISCHMAN, Robert M.
- GIZA, Jim
- KIM, Joachim
- KLUTE, Rainer
- PRUD'HOMMEAUX, Eric
- MCNEIL, Chris
- PETIT, Bertrand
- PUZIO, Maciej
- REAGEN, Jeff
- WEI, John
- WOODWARD, Jennifer

## Release 4.0D February 12 1996

This upgrade release fixes some bugs and it adds functionality for posting data from memory. This is the full list of changes:

- Optimized HTTP request header by taken away an "Accept:" line pr accepted content type and instead use the commna notation.
- Introduced HTMemory as dynamic memory handler. This module is a part of the WWWUtils interface and it handles better management of dynamic memory. You can find a full description in the User's Guide.
- We now have an updated list of all public functions exported from the Library. It's available as wwwlist.txt
- We also present an updated list of all public interfaces available in the Library. You can find it in the Library Internals.
- PUT and POST from memory is implemented. You can now post data from memory using the POSTWeb model as for posting remote data objects. The Interface is described in HTAccess module. There is a very small dummy test implemented in the Line Mode browser. You can activate it if you typeedit from the command line.
- The Mini server now runs (although crude) as a proxy. It is capable of serving data as a HTTP/HTTP proxy. It is based on the internal Library event loop and is therefore highly portable. It is not intended to be a full featured server but a test implementation which shows how to use the Library in server applications.
- Bug fixed that caused the following problem: If there hasn't been made a connection between the net->target and the request->output_stream then the latter is not freed if the request is interrupted.
- The referer URL header can now contain a unlimited length URL
- A resolver callback function has been introduced in the HTTee stream. This allows the caller to assign a callback function to resolve conflicts between the return codes of the two streams.
- The request object as been added as a calling parameter to the HTFWrite stream creation method. This allows errors from writing to a file to propagate back to the request object.
- The three streams `HTSaveLocally`, `HTSaveAndExecute` and `HTSaveAndCallBack` have been optimized and they now all use the HTFWrite stream creation method
- We have a new module called HTTPGen. It generates general HTTP headers. These headers were a part of the MIME header generator, but by isolating them, we can use the MIME header as a generic MIME entity header generator.
- Created HTErrorStream which always returns HT_ERROR. It replaces the HTBlackHole has been replace with HTErrorStream in many places in order to speed up performance
- Made HTTP response stream (which parses the response line only) into a converter so that we can forward the output exactly as received from the remote HTTP server. This is important for proxy applications and other applications that want to see the output untouched.
- The HTChunk module has been made more solid and the amount of memory allocations has been limited.
- Memory cleanup fixed in content length counter stream and FTP module
- Introducing HT_CLOSED and HT_PAUSE for handling streams. This was required, especially after HTTP supports persistent connections where a document is not delimited by a closed connection.

## Release 4.0C January 23 1996

- Automatic redirection and Access authentication has been take n out of the HTTP module. Instead the new mechanism with request callback functions are used so that the application can register handlers to handle these situations. The reason for this change is that not all applications are interested in having this functionality performed automatically.
- Authentication handler and redirection handler added to both the Line Mode Browser and the Command Line Tool
- Added three possible return codes on which a request callback function can be called:
  - HT_PERM_REDIRECT for permanently moved objects
  - HT_TEMP_REDIRECT for temporarily moved objects
  - HT_NO_ACCESS for insufficient credentials
- PUT and POST do now work reliably in the Line Mode Browser and the Command Line Tool. Both can PUT or POST a document from either a remote HTTP server or the local file system to a remote HTTP server.
- An important bug-fix in the internal event manager that prevented a socket to be registered for multiple events at the same time.
- Cleanup of the POSTWeb management in the file module and the HTTP module
- In addition to progress notification on READ we now support progress notification when sending a data object
- Spelling mistake fixed. preemtive is changed to preemptive
- The W3C Mini Robot has now the ability to stop at a certain depth while traversing the Web.

## Release 4.0A December 11 1995

- Created the include HTTPUtil.html - a C file may follow
- Changed HTDoAccept so that it automatically inserts the new socket descriptor in the Net object.
- HTLoad_terminate moved from HTReqMan to HTHome. It is not automatically set up in HTLibInit anymore
- Made HTAnchor and HTLink opaque data objects
- changed HTAnchor_linkResult to HTLink_result
- changed HTAnchor_linkMethod to HTLink_method
- Changed HyperDoc to simply a void pointer. This makes it more generic and the application does not have to actually treat it as a document anyway
- Introduced the WWW_DEBUG internal format that can be used to redirect debug information, for example from a HTTP redirection message etc.
- Request object added to HText_new methods
- changed HTExtParse to HTXParse throughout - H&kon
- HTXParse now null-terminates buffer - H&kon
- return codes from HTTee changed - H&kon
- content-length initialized to -1 - H&kon
- Fixed bug for handling HEAD in HTTP and MIME streams
- Handles of persistent connection is now a semaphore and not a bool
- Changes the event loop so that a timeout handler can return HT_OK or HT_ERROR. If the code is not HT_OK then stop the event loop
- Changed request of header enumeration:
  - General headers have the prefic HT_G_
  - Request headers have the prefic HT_C_
  - Server headers have the prefic HT_S_
  - Entity headers have the prefic HT_E_
- Separated file suffix initialization into HTBInit
- Changed the names in HTChunk to be consistent with the Module_method scheme
- Introduced HTBInit.c for setup of file suffixes

## Release 4.0 December 1 1995

## Alpha Release 7, November 28 1995

- Added a backlog parameter to the HTDoListen() function
- Added a parameter for handling `server modules` to the Protocol module. An access scheme (for example HTTP, can now be registered together with a client module and a server modele
- Added HTServDocument to the HTAccess module in order to better support server applications.
- Made WWWNews.html, WWWHTTP.html, WWWMIME.html, and WWWFTP.html include files to be used by applications.
- Changed functions with the name `preemptive` to `preemptive` it was a spelling mistake

## Alpha Release 6, November 20 1995

- Removed remaining `ARGS` and `PARAMS` from the sources. All function declarations and definitions now follow the ANSI standard.
- Changed HTAlert to be a registration module instead of a module to be overriden by an application. Now you can register a Dialog module as a callback function which is a much more generic moduel. It also means that there are no more English text in the Core of the Library - it's all in a application module. The Library provides a default implementation in the new HTDialog module.
- Taken the WWW relevant stuff out of HTString and put it into the new module called HTWWWStr. The latter is a part of the core whereas the former is generic string utilities.
- Made the global variable `HTLibraryVersion` local to HTAccess. The are now only `WWW_TraceFlag` left as a global variable in the whole Library.
- There are now four main include files. They are called:
  WWWUtil.h
    The WWW Utility module contains a lot of the functionality that makes it possible to make applications, that is container modules for data objects, basic string functionality etc. This module is the basis for all of the following modules and is used extensively.
  WWWCore.h
    The WWW Core module is a set of registration modules that glues an application together. It contains no real functionality in itself; it is for example not capable of loading a HTML document. It only provides a large set of hooks which can be used to add functionality to the Library and to give an application real life. We will here a lot more to the structure of the core, and much of this guide is actually describing how to add functionality to the core.
  WWWLib.h
    This include is the main include file for the Library. It basically consists of the WWWUtil.h and the WWWCore.h so that the application only needs to include this one instead of two.
  WWWApp.h
    This module contains a huge set of modules that can be hooked into the Core Library and make the application work. In contrast to the Core part, you can pick exactly the modules you want from the WWWApp.h in order to create your special application whether it is a server, a client, a proxy, a robot or any other Web application.
- HTGuess stream is now a converter just like any other converter, and it can be registered by the application if wanted
- `HTClientHost` (global var) is removed from the Library as it wasn't use there at all
- Introduced HTHome module as part of the application specific part of the Library. It contains handy functions for the application.
- HTFindRelatedName() and HTHomeAnchor() are moved from HTAccess.c to the new module HTHome.c
- HTImProxy is taken out as it can be handled in the setup of the converters
- Created HTList_appendObject() in HTList module which adds an element to end of list
- Introduced pre request callback functions in HTNet and changed the interface. It's described in User's Guide. This means that an application can register any action to be executed either before and/or after a request is done. This is described in detail in the User's Guide.
- HTHome module contains default callback functions to be called before and after a request.
- Removed the HTInputSocket_get* functions from HTSocket as they are no more needed (they were non-reentrant and belonged to the old interface)
- Added the following HTLib_* functions to the HTAccess module:
  - CONST char * HTLib_name (void)
  - CONST char * HTLib_version (void)
  - BOOL HTLib_secure (void)
  - void HTLib_setSecure (BOOL mode)
- Library is now handling cleanup of anchors in HTLibTerminate() as it really is a part of the core.
- Default addresses are taken out of HTAccess and added to HTHome. They were mainly some default addresses for `WWW_HOME` etc.
- The Library is now not using env variables at all
- The flag `WWW_WIN_ASYNC` introduced to use the new async window interface. Add this define to your project if you want it
- HTsocketWin and HTwinMsg made internal to HTEvntrg.c. They can now be accessed through the methods
  - HTEvent_setWinHandle
  - HTEvent_winHandle
- Added the following formats to the default initialization:

      	www/unknown -> HTGuess_new
      	text/x-www-rules -> HTRules

- Changed format image/x-tiff to image/tiff and image/x-png to image/png
- Finished the News module using non-preemptive sockets. Final testing is still missing
- Changed HTRules so that it now is a stream. It also handles line wrapping and has a much more solid parsing mechanism. See description in User's Guide for more details.

## Alpha Release 5, November 8 1995

The Library has now undergone a major restructuring in order to define the APIs between the various parts and to make it more modular. The new architecture is described in the Architecture document and includes a new Net manager that handles a request queue, a DNS manager that handles persistent connections and a well defined Request manager where the HTRequest object is an opaque object.

### Core Modules

- Generalized the Error Manager to work on lists instead of as directly on a request object. This makes it possible to use the error manager in all situations.
- Changed HTAppName and HTAppVersion to parameters to HTLibInit() instead of as global parameters.
- Introduced a new main include file called WWWApp.h which contains applications specific modules. None of these modules are actually required to compile and link the Library, but the application can use them if needed.
- None of the access modules (HTTP, FTP, NNTP, etc.) are set up by default anymore. This is now for the applications to do.
- Changed TRACE to WWWTRACE as it interferes with macro on NT
- The balanced binary tree in HTBtree is not used anymore. The functionality is now provided by the new HTArray module that is a dynamic array of pointers. It is much like the HTChunk module but for pointers instead of dynamic strings. The advantage is that the fast qsort algorithm can be used on the array.
- Moved the two functions `HTWWWTLocal()` and `HTLocalToWWW()` from the HTFile Module to the HTString module for converting between local file names and URLs
- It is now possible to register a call back function together with a timeout that is used in the select call of the event loop. When the select() call times out, the call back function is called. The registration can either be so that the call back always is called when that the select call times out or only when Library sockets are in use.
- We have a port to PowerMac and 68K!!! This has been provided by Steven T. Roussey <sroussey@eng.uci.edu> and Brad Barber <barber@well.com>
- We have changed HTThread to HTNet.c as thread was too confusing. This module has been cleaned up and rewritten so that HTNet.c now contains the Net manager. The Net manager controls the net access so that we only keeps a specified amount of sockets open simultaneously (called a request queue). It also partly controls the management of persistent connections together with the DNS Manager.
- The HTRequest Object is now known to the Request Manager only. It is accessible through a lot of methods just like the Anchor object etc. The HTAccess module is now a user interface to the Request Manager but it doesn't have to be used - you can use the Request Manager directly but often it is easier to go through the Access Module.
- The Protocol object has been turned into an object internal to the Protocol manager. This means that protocol information can be accessed via a set of methods provided by the manager.
- We have changed case sensitive search to insensitive search when finding an access methods (HTTP, FTP, telnet etc.) for a URL. This catches silly errors in URLs like HTTP://www.foo.com
- The static protocol declarations have been replaced with a set of parameters to the creation method of a protocol object in the Protocol Manager which is more handy.
- We added HTProtocol_delete() as method in the Protocol manager. This means that it is now possible to unregister a protocol at runtime. If you are on a platform with dynamic linking (for example DLLs) then this can save a lot of space.
- Introduction of application call back function for memory cache. This is a part of separating the HText module and also to make the memory cache manager more flexible. An example implementation can be found in the GridText module in the Line Mode Browser.
- Full support for the HTLink object that binds together two anchors. This is a requirement for keeping track of the Post Web.
- URL fragment identifiers were case insensitive - they are now case sensitive
- Added `result` field to the HTLink so that the result of a posting operation is stored in the link object. This means that the application can see which post operations succeeded and which didn't. This can for example be used in a GUI client to show the relations between the source and destination anchor as "dim" links.
- Fixed bug in put mechanism that caused destinations to accumulate in the postweb. Now `old' destinations are still registered but not included in a new postweb - they can, however, be discarded all together, but often the information is nice to have. On a GUI client, it can be shown as 'dimmed' destinations.
- Removed remaining outputs directly to stdout using fprintf(). Now all goes through HTAlert module. This was a problem in some of the protocol modules as well (especially in the Telnet module).
- The `CacheItems` structure is removed from anchor object and replaced by `(BOOL) CacheHit`. If `CacheHit=YES` then the format negotiation and suffix binding is not used in HTFile Module but the object is loaded directly (from the local file cache) using non-blocking I/O
- Internal DNS/hostname cache optimized and made more flexible to support persistent connections for all protocols that support this, for example HTTP, FTP, and NNTP. The first version has support for HTTP only, but the other ones will follow shortly. and multiple connections to same address. You can now control the garbage collection of DNS entries based on time. The DNS object keeps also information about the remote server (class of request, for example HTTP or FTP and the type of server, for example HTTP/1.0, HTTP/0.0 etc.). This means that it is possible to adjust a request to a remote server once the type is known. For example, the Library now distinguishes between HTTP servers version 0.9, 1.0, and 1.1. New classes and versions can be registered at run time just like protocol modules.
- HTDoConnect rewritten as a state machine which makes it a lot easier to understand and change. It is furthermore and important part of the persistent connection management.
- Removed `HTMaxRedirect` as a global variable. It is now private to Request manager with two methods to access it
- Support for context swapping and call back function in the HTRequest object. This allows the application to distinguish between multiple ongoing requests. See more information in the User's Guide.
- Bug fix in HTTCP.c HTGetHostName thanks to "dave (d.) mielke" <davem@bnr.ca>

### Protocol Modules

- We have a first version of a new News module which supports POST, persistent connections and a lot of more efficient NNTP commands.
- Re-implemented long directory listings for FILE and FTP access using streams. The HTML machinery is now separated into the new HTDir module. It provides long directory listings for Unix, NT, and VMS.
- Support for persistent connections in HTTP requests. This has been enabled by the generic model in the DNS manager.
- Support for the methods DELETE, LINK, and UNLINK.
- Re-implemented HTFTP module using persistent connections, multiplexed (non-blocking) sockets and streams for input and output. In fact the FTP module is now very capable and it's half the size of what it was because the Library in general supports the features needed in the FTP module. NOTE: Generation of HTML objects from directory listings is disabled for the moment as we are re-implementing it using streams. However, now it is possible to get the raw source code directly from the FTP server by typing:

      	www -source ftp://ftp.w3.org

- Re-implemented Gopher module so that it uses streams for input and output instead of the obsolete HTSocket_getCharacter() method. The module now also uses non-blocking I/O as the HTTP module and the file module. A result of using streams is that you now can obtain the "real" source (the ASCII object sent by the gopher server) by using WWW_SOURCE as the output format. Before the source was equivalent of the source of the HTML object that was generated on the fly.
- Updated Telnet module to understand URL format user:passwd@host:port. Cleaned up the code and fixed a set of bugs at the same time.
- Support for Host header in HTTP Request module. Actually this was Orig-URI but it was changed on the fly.
- Fixed bug on HTTP redirect if no body part was present. This is the new "trend" especially from Netscape's server. The old servers always sent back a small HTML document explaining if the client didn't understand automatic redirect.

### Stream Modules

- We now have a MIME multipart parser stream which supports nested MIME multipart messages. This stream sets up a new MIME parser stream each time it finds a new body. Preamble and epilog messages are ignored by default but can be redirected to the special Debug Stream output of the Request object.
- We have added a content counter stream and a buffer stream in HTConLen module. This can be used to count the number of bytes in a data object either to be sent to a remote server or as a check of a received body. Together with the Content Length counter stream there is also a buffer stream that can buffer up to a certain amount of dat before it goes transparent.
- We have replaced the internal format identifier `www/mime` with the MIME conforming `message/rfc822` format. This may affect the setup of stream converters that used the old format.
- We have also added a new HTMIMERq module which is responsible for creatin MIME metainformation when sending requests. This is used, for example, by the HTTP protocol module and the NNTP protocol module
- For the first time, it is not required to define dummy definitions of the external declared function in the HText Interface. It is now only referenced from the HTML module and the Plain Text Presentation module. This means that applications that do not use the HTML/HText interface no more have the modules linked into the final object code.
- The SGML module is no longer included anywhere anymore except where necessary. The structured stream definition can be found in HTStruct module
- Make registration of callback function for unknown MIME headers in the MIME parser. The application can now more easily experiment with new headers. The registration process is described in the section How to get Started Writing an App
- Added support for png (lossless graphics format) (patch from unknown?) into the Guess stream
- Bug fixed in HTML parser It couldn't handle more than 20 nested HTML tags which can happen for example in auto-generated HTML documents.
- HTLoadError taken out completely. Replaced by the error manager. It was for (stupid) historic reasons put into the HTML parser.

### Application Modules

- HTInteractive made a private flag to HTAlert.c. It can now be reached via two methods in the module.
- All functions in the Alert Module now has a request object as part of the calling parameters. The reason is that then the implementation of this module can call a registered call back function (as described above) so that the user message can be put into the right context.
- Mem leak fixed in HTLog module and added result of request to the log file. The log module is no longer called in the Library at all so if you do not use then it is not included in the application.
- Rewritten HTHistory module to perform a better history mechanism - the old version did not work properly. Some of the new features are
  - Support for multiple history lists. You can use the context information in the request object to find the right list at any given time.
  - The list now supports both back and forward for navigation. The list is no more "back trace with deletion".
  See User's Guide for more information
- Introduced HTProgress() notifications for the following operations
  - DNS lookup
  - connect to remote host (either passive or active)
  - read data from network
  - write data to network
  - request finished
  - waiting for free socket
  On each of these operations, the library calls HTProgress() with a code so that the application can define what to do with it.

### Generic Utilities

- Introduced HTChunkData() and HTChunkSize() as methods in the HTChunk module. No more need to look into the HTChunk object itself.
- Changed HTStat to HT_STAT and HTLStat to HT_LSTAT as they are macros
- The `HTSimplify()` function in the HTParse module now follows the RFC 1808 Specification
- Fixed bug in HTCanon() that got confused about <http://teller.datawave.net:80/test/../imx/weelogo.gif> thanks to Henry Minsky
- HTCanon() made private to HTParse module as it is called from HTSimplify() only
- All replaced with (wb|ab) if known binary output. This was a problem on Windows 3.1 platform as it inserted extra CRLF line terminators.
- Created HTNumToStr() in HTString Module to convert a number to a string using prefixes. This can be used in the progress notification to write Read 1.6K etc.