Reggae tutorial: http.stream - Revision history

Krashan: This article is dead and may be deleted.

2010-08-26T16:00:19Z

This article is dead and may be deleted.

Krashan: /* What is http.stream class? */ Note on media streaming.

2010-08-26T13:38:02Z

‎What is http.stream class?: Note on media streaming.

Krashan: /* Basic download operation */ More notes.

2010-08-26T13:35:25Z

‎Basic download operation: More notes.

Krashan: /* Basic download operation */ Removed misleading statements

2010-08-26T13:30:20Z

‎Basic download operation: Removed misleading statements

Krashan: /* Basic download operation */

2010-08-26T13:29:06Z

‎Basic download operation

Krashan: /* Basic download operation */ More contents.

2010-08-26T13:27:21Z

‎Basic download operation: More contents.

Krashan: /* Basic download operation */

2010-08-26T13:26:38Z

‎Basic download operation

Krashan: /* Basic download operation */ Contents.

2010-08-26T13:17:38Z

‎Basic download operation: Contents.

Krashan: /* What is http.stream class? */ Features.

2010-08-26T13:02:32Z

‎What is http.stream class?: Features.

Krashan: /* What is http.stream class? */ Contents++;

2010-08-24T16:41:29Z

‎What is http.stream class?: Contents++;

← Older revision		Revision as of 16:00, 26 August 2010
Line 1:		Line 1:
−	~~''Grzegorz Kraszewski''~~	+	dead article
−
−	~~==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.
−	* The class supports chunked transfer and media streaming over HTTP.
−	* 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:~~
−
−
−	~~<tt>Object *http;<br>~~
−	~~UBYTE buffer[10240];    /* 10 kB of data */<br><br>~~
−	~~if (http = NewObject(NULL, "http.stream",<br>~~
−	~~  MMA_StreamName, "www.morphzone.org",<br>~~
−	~~TAG_END))<br>~~
−	~~{<br>~~
−	~~  DoMethod(http, MMM_Pull, 0, buffer, 10240);<br>~~
−	~~  DisposeObject(http);<br>~~
−	~~}</tt>~~
−
−
−	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==~~
−	~~==Network error reporting==~~
−	~~==Additional features of http.stream==~~

@@ Line 18: / Line 18: @@
 * 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.

@@ 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==
 ==Network error reporting==
 ==Additional features of http.stream==

@@ Line 31: / Line 31: @@
 * 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. It can be easily done using some Reggae output class instead of calling ''MMM_Pull()'' directly (it will be discussed later).
+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:

@@ 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.
+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.
 ==Downloading to disk on subprocess==
 ==Network error reporting==
 ==Additional features of http.stream==

← Older revision		Revision as of 13:02, 26 August 2010
Line 12:		Line 12:

	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:		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==

@@ Line 11: / Line 11: @@
 ==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.
+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:
 ==Basic download operation==