HTTPStreamer_Amiga

httpstreamer.hwp
================

This plugin enables Hollywood to open and stream files from HTTP sources as if
they were
stored on a local drive. Once this plugin has been activated, all Hollywood
functions
that deal with files will "automagically" be able to open files from HTTP
sources as
well.

httpstreamer.hwp uses a sophisticated multi-threaded design for highly efficient
HTTP
streaming. Each HTTP connection is managed by a dedicated thread for optimal
performance.
The plugin also supports Hollywood 6.0's new streaming APIs which means that you
will
be able to stream audio and video files from HTTP sources with plugins like
avcodec.hwp.


Requirements
============

This plugin requires at least Hollywood 6.0 since it uses the file adapter and
streaming
APIs introduced with Hollywood 6.0.

For video and audio streaming through avcodec.hwp, you need at least version 1.3
of
the avcodec.hwp plugin.


Usage
=====

There are two ways to use this plugin: You can either activate the plugin
globally by
()REQUIRE-ing it. To do this, simply put the following preprocessor command at
the top
of your script:

    ()REQUIRE "httpstreamer"

If you activate the plugin via ()REQUIRE, it will become globally available and
all
ensuing commands that deal with files will support the opening of files from
HTTP
sources. For example, you could do something like this then:

    LoadBrush(1, "http://www.example.com/testpicture.jpg")

If you only need to open very few files from HTTP sources, you can also choose
to not
activate the plugin globally via ()REQUIRE but simply use the "Adapter" tag
offered
by most Hollywood commands to tell the respective Hollywood command to open the
file
using the httpstreamer.hwp plugin. Here is an example:

    LoadBrush(1, "http://www.example.com/testpicture.jpg", {Adapter =
"httpstreamer"})

By using the "Adapter" tag, LoadBrush() is told to open the specified file using
the specified adapter, which is "httpstreamer" in our case. Thus, the "Adapter"
tag
allows you to use this plugin even without having ()REQUIRE-d it first. 

Keep in mind that all files declared in the preprocessor commands are linked
automatically
into your applet or executable when Hollywood is in compile mode. Thus, if you
do the
following, the file will be downloaded and linked to your applet or executable:

    ()BRUSH 1, "http://www.example.com/testpicture.jpg"
    
This means that your applet or executable will not download the file any more
but they
will use a copy of the file that has been linked into the applet or executable!
If
you want the applet or executable to always use the copy on the HTTP server, you
have
to make sure that the file is never linked to the applet or executable. This can
be
achieved by setting the "Link" tag to FALSE:

    ()BRUSH 1, "http://www.example.com/testpicture.jpg", {Link = False}
    
When done like this, Hollywood will never link the file into your applet or
executable.
Instead, it will always be downloaded from the given URL.    
    

Options
=======

httpstreamer.hwp supports several options which can either be passed to
()REQUIRE or to
the httpstreamer.SetConfig() command. Note that ()REQUIRE expects a table which
can
contain multiple options at once whereas httpstreamer.SetConfig() only accepts a
single
option at a time.

The following options are currently available:

Fail404:
This tag specifies whether or not httpstreamer.hwp should fail with a "file not
found"
error when you pass a URL that points to a non-existent file. Normally, when you
request
a non-existent file, HTTP servers will generate a special HTML page with a "404
- file
not found" error, and send that to you instead. So you will always be getting a
file
even if you are requesting a non-existent file which can be confusing. If you
really want
this behaviour, set this tag to FALSE. Then httpstreamer.hwp will never fail for
any
HTTP files and will always deliver an error page in case of a non-existent file.
By default,
this tag is set to TRUE which means that no error page is generated and
httpstreamer.hwp
will fail to open non-existent files.

Redir:
Specifies whether or not the web server is allowed to redirect you to a new URL.
This
defaults to TRUE which means that redirection is allowed.

Timeout:
This tag allows you to set a connection timeout in milliseconds. The default is
10000
which means that httpstreamer.hwp will timeout in case the server doesn't reply
within
an interval of 10 seconds.

Proxy:
You can specify a proxy server here that should be used when making connections.
By
default, httpstreamer.hwp doesn't use any proxy server.

UserAgent:
This tag allows you to change the user agent that httpstreamer.hwp sends to the
target
server. This is useful with servers that refuse to cooperate with unknown user
agents.
By default, httpstreamer.hwp will send "HTTPStreamer.hwp" in the user agent
field of
HTTP requests.

TmpFileThreshold:
When requesting larger files, httpstreamer.hwp will use a temporary file for its
buffer
instead of memory. This tag allows you to specify a threshold value in bytes
that
defines when httpstreamer.hwp should use a temporary file instead of a memory
buffer.
This defaults to 16277216 bytes which means that all files larger than 16 MB
will be
buffered on disk whereas all files smaller than 16 MB will be buffered in
memory.

RamFileThreshold:
This is only supported on AmigaOS and compatibles. When using temporary file
buffering
(see the documentation of "TmpFileThreshold" above), this tag allows you to set
a
threshold value that defines whether the temporary file should be created in RAM
disk
or on your hard drive. Whenever the temporary file is bigger than the threshold
value
specified here, it will be created on your hard drive. Otherwise it will be
created
in T: on your RAM disk. Obviously, this tag must be set to at least the value of
"TmpFileThreshold". It defaults 33554432 bytes on AmigaOS 3 and 104857600 bytes
on
all other AmigaOS compatibles. This means that on AmigaOS 3 all temporary files
smaller than 32 MB will be written to T: whereas on all other systems all
temporary
files smaller than 100 MB will be written to T:.

IOBufSize:
This tag allows you to set the IO buffering size. It's normally not necessary to
tinker
with this. Defaults to 16384 bytes.

SetStreaming:
This tag allows you to set whether httpstreamer.hwp should inform Hollywood that
its file handles are actually streams. By default, httpstreamer.hwp does so.
This
allows Hollywood to try to avoid operations that are inefficient on streaming
sources
like excessive seeking operations. If you set this tag to FALSE, Hollywood
won't be made aware that the file handles managed by httpstreamer.hwp are
actually
streams. This might entail undesirable consequences because Hollywood might try
to
seek the file handle to the end and since the HTTP protocol doesn't easily
support
direct byte seeking, the seek operation has to be emulated which can be really
expensive.
Seeking to the end of a HTTP stream for instance means that httpstreamer.hwp
will
have to download the entire file before it can continue! Thus, you normally
won't
want to set this tag to FALSE but keep it to TRUE, which is the default.

SetNoSeek:
If this tag is set to TRUE, httpstreamer.hwp won't support seeking on its file
handles. Note that if you set this tag to TRUE, several file format handlers
which
depend on the seek functionality might stop working. That's why it's recommended
to leave this tag at its default value, which is FALSE.

Here is an example of how to use these tags:

    ()REQUIRE "httpstreamer", {UserAgent = "Firefox", Timeout = 20000}

                -OR-

    httpstreamer.SetConfig("UserAgent", "Firefox")
    httpstreamer.SetConfig("Timeout", 20000)

Using httpstreamer.SetConfig() is especially useful if you do not want to
()REQUIRE
the plugin.


Troubleshooting
===============

You have to be careful when using HTTP URLs in preprocessor commands because
when
Hollywood is in compile mode, it will link all files declared in the
preprocessor
commands to the applet or executable by default. This means that Hollywood will
download all files declared in the preprocessor commands and link them which is
probably not what you want in that case. You probably want Hollywood to always
use
the copy from the server instead of a linked copy. See the section "Usage" above
for information on how you can achieve this.


History
=======

Version 1.1:    (25-Mar-17)
- New: Added 64-bit builds for Windows, Linux, and Mac OS
- New: Added support for Hollywood 7.0's help string feature
- Fix: Documentation wrongly documented "http.SetConfig" when it had to be
"httpstreamer.SetConfig"
- New: Added "Encoded" option; when this is set to TRUE using SetConfig(), HTTP
Streamer will expect
  encoded URLs instead of unencoded URLs (requested by Lazar Zoltan)
- Fix: HTTP Streamer didn't handle HTTP redirect requests correctly (reported by
Dominique Vanderveken)

Version 1.0:    (26-Sep-15)
- First release


Future
======

Direct seeking using HTTP range requests would be nice but not all servers
support it.


Bugs
====

Please report any bugs or issues via the Hollywood forums at
http://forums.hollywood-mal.com/


Copyright
=========

This plugin is (C) Copyright 2014-2017 by Andreas Falkenhahn
<andreas()airsoftsoftwair.de>
Refer to the COPYING file in this package for conditions concerning distribution
of this plugin. Visit http://www.hollywood-mal.com/ for more information
on Hollywood and more plugins.

Copyright (C) 2014-2015 Andreas Falkenhahn <andreas()airsoftsoftwair.de>

This plugin (the "program") is provided "as-is" and the author cannot be
made responsible of any possible harm done by it. You are using this plugin
absolutely at your own risk. No warranties are implied or given by the
author.

This plugin may be freely redistributed as long as no modifications are made
to it.

DISCLAIMER: THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDER AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE
COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE
PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS
OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.