Difference between revisions of "Reggae tutorial: http.stream"

From MorphOS Library

(Basic download operation: Removed misleading statements)
(Basic download operation: More notes.)
Line 47: Line 47:
  
  
This code has the basic error handling. It won't pull data if the object is not created for any reason. For more sophisticated error handling see [[#Network_error_reporting|Network error reporting]] section. Of course ''http.stream'' class has to be loaded from disk (using ''OpenLibrary()'') before ''NewObject()'' is called.
+
This code has the basic error handling. It won't pull data if the object is not created for any reason. For more sophisticated error handling see [[#Network_error_reporting|Network error reporting]] section. Of course ''http.stream'' class has to be loaded from disk (using ''OpenLibrary()'') before ''NewObject()'' is called. Note that URL passed has no "http://" prefix. As the class handles HTTP only, protocol prefix is not needed. Note also that the page will be loaded in spite of the first server response being "302 Found", thanks to automatic redirection. The real URL is "www.morphzone.org/modules/news/". The whole connection process may be watched in details (including request and response header dumps) by running MediaLogger and then tested application.
  
 
==Downloading to disk on subprocess==
 
==Downloading to disk on subprocess==
 
==Network error reporting==
 
==Network error reporting==
 
==Additional features of http.stream==
 
==Additional features of http.stream==

Revision as of 14:35, 26 August 2010

Grzegorz Kraszewski

Idea of live software update

Live software update over Internet is becoming popular in mainstream operating systems and its applications. It is comfortable to users, allows for fast distribution of bugfixes and security updates and also (what is important for commercial products) creates an additional channel of advertising. The general idea of live update is simple. An application connects to a remote server, checks for updates, download them if any found, then install new files in proper places. After that application asks user for a restart and optionally restarts itself.

While it sounds easy in the above description, there are some obstacles on the way. MorphOS provides network connections handling on TCP/UDP protocol level (or socket level API-wise). Some higher level protocol must be used to handle update check and files downloading. It may be some custom thing (which has a big disadvantage that it must be implemented on the server side too), or some standard protocol, like FTP or HTTP. While FTP seems to be better suited, looking at its name, HTTP is more versatile as it allows for easy implementation of additional features on server side like download counters, dynamic content generation, sending information to the server and more.

HTTP is not a very complicated protocol, handling it at socket level is some serious work however. On the other hand using an external application like wget gives very little control over downloading process. MorphOS had no embeddable HTTP client, but now it has one, which is Reggae http.stream class. It is a lightweight implementation of HTTP/1.1 protocol. The only limitation is that it supports GET requests only (it may support also POST in the future).

What is http.stream class?

The http.stream class is just a HTTP/1.1 client which may be used either as a data source for Reggae framework, or standalone as a single component. It allows for easy download of any resource reachable with HTTP GET request. It has also some higher-level functions, which make using HTTP protocol easier. Here is a brief list of features:

  • Completely encapsulates socket communication level into an easy to use programming interface. Knowledge of bsdsocket.library API is not required at all, some general knowledge about Internet and HTTP would be an advantage however.
  • Unlike bsdsocket.library base instances, http.stream objects may be shared between processes.
  • The class has builtin parser of HTTP response headers.
  • The class has also an easy to use HTTP request header builder, so custom fields may be added to the header.
  • HTTP proxies are supported.
  • Optional user agent spoofing is possible.
  • When connecting, HTTP redirections may be followed automatically.
  • Easy protocol debugging via MediaLogger.

Basic download operation

Basic download operation starts from creation of http.stream instance. URL for the requested resource and other connection details are passed to the constructor as attributes. After succesful construction, response data may be pulled from the output port of the object by calling MMM_Pull() method. When application is finished with downloading data, it just disposes the object.

Following operations are performed while the object is constructed:

  • Connection. URL is parsed, hostname and port are extracted and used to make a TCP connection to the remote host. A DNS query is performed before, to convert hostname into an IP address.
  • Request. HTTP request is built and sent to the remote host.
  • Reply header reception. The object receives HTTP header and parses it.

After succesful object construction, the object is ready to pull response data from its output port. Note that object construction is synchronous to the application. In case of problems like slow DNS response, or connection timeout, the application is waiting. For GUI based applications the whole download should be ran in a subprocess.

Following snippet of code downloads the first 10 kB of MorphZone main page:


Object *http;
UBYTE buffer[10240];    /* 10 kB of data */

if (http = NewObject(NULL, "http.stream",
  MMA_StreamName, "www.morphzone.org",
TAG_END))
{
  DoMethod(http, MMM_Pull, 0, buffer, 10240);
  DisposeObject(http);
}


This code has the basic error handling. It won't pull data if the object is not created for any reason. For more sophisticated error handling see Network error reporting section. Of course http.stream class has to be loaded from disk (using OpenLibrary()) before NewObject() is called. Note that URL passed has no "http://" prefix. As the class handles HTTP only, protocol prefix is not needed. Note also that the page will be loaded in spite of the first server response being "302 Found", thanks to automatic redirection. The real URL is "www.morphzone.org/modules/news/". The whole connection process may be watched in details (including request and response header dumps) by running MediaLogger and then tested application.

Downloading to disk on subprocess

Network error reporting

Additional features of http.stream